Polycam Reconstruction API

Creates a new API token for the specified workspace. The raw token value is returned only in this response — store it immediately.

Request Body

Example Request

curl -X POST https://poly.cam/api/account/api-tokens \
  -H "Authorization: Bearer <firebase-id-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace": { "id": "ws_abc123", "type": "org" },
    "name": "CI Pipeline Token",
    "expiresInDays": 90
  }'

Response 200

{
  "token": "poly_a1b2c3d4e5f6...64 hex chars",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "CI Pipeline Token",
  "prefix": "poly_a1b2c3d4",
  "scopes": ["content_management", "reconstruct"],
  "createdAt": 1706140800000,
  "expiresAt": 1713916800000,
  "message": "Save this token now - it will not be shown again!"
}

Error Responses

Lists all API tokens for a workspace. Raw token values are never returned — only the prefix (first 13 characters) is shown.

Query Parameters

Example Request

curl https://poly.cam/api/account/api-tokens?workspaceId=ws_abc123&workspaceType=org \
  -H "Authorization: Bearer <firebase-id-token>"

Response 200

{
  "tokens": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "CI Pipeline Token",
      "prefix": "poly_a1b2c3d4",
      "scopes": ["content_management", "reconstruct"],
      "createdAt": 1706140800000,
      "createdBy": {
        "id": "user_xyz",
        "username": "alice"
      },
      "expiresAt": 1713916800000,
      "revoked": false,
      "revokedAt": undefined
    }
  ]
}

Error Responses

Revokes an API token. Revoked tokens can no longer be used for authentication. This is a soft delete — the token record is preserved with a revokedAt timestamp.

Path Parameters

Example Request

curl -X DELETE https://poly.cam/api/account/api-tokens/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer <firebase-id-token>"

Response 200

{
  "success": true,
  "message": "Token revoked"
}

If the token was already revoked:

{
  "success": true,
  "message": "Token already revoked"
}

Error Responses

Returns the current prepaid API credit balance for the authenticated token's workspace.

Example Request

curl https://poly.cam/api/v1/credits \
  -H "Authorization: Bearer poly_a1b2c3d4e5f6..."

Response 200

{
  "balanceCredits": 1500,
  "updatedAt": 1706140800000
}

Error Responses

Returns a paginated ledger of credit changes for the authenticated token's workspace, ordered by creation time with newest entries first.

Query Parameters

Ledger Entry Fields

Example Request

curl https://poly.cam/api/v1/credits/ledger?limit=25 \
  -H "Authorization: Bearer poly_a1b2c3d4e5f6..."

Response 200

{
  "entries": [
    {
      "id": "ledger_abc123",
      "kind": "charge",
      "amountCredits": -1050,
      "balanceAfterCredits": 450,
      "createdAt": 1706140800000,
      "endpoint": "POST /api/v1/captures",
      "description": "Reconstruction (splat)"
    },
    {
      "id": "ledger_def456",
      "kind": "deposit",
      "amountCredits": 1500,
      "balanceAfterCredits": 1500,
      "createdAt": 1706137200000,
      "description": "Credit purchase"
    }
  ],
  "cursor": "1706137200000"
}

When there are no more entries, the cursor field is omitted from the response.

Error Responses

Creates a new capture, reserves its reconstruction job in waitingForUpload, and returns a signed upload URL for the session.zip file. Upload to this URL, then call Confirm session.zip Upload to make the job runnable.

Request Body

Example Request

curl -X POST https://poly.cam/api/v1/captures \
  -H "Authorization: Bearer poly_a1b2c3d4e5f6..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "Office Scan", "externalId": "JOB-123", "mode": "photo", "numKeyframes": 20 }'

Response 201

{
  "capture": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Office Scan",
    "externalId": "JOB-123",
    // ... same shape as the Capture Object
  },
  "jobId": "7f4f2b6c-0a5d-4b5a-9f1f-0f3d0d3f9a12",
  "mode": "photo",
  "status": "pending",
  "upload": {
    "url": "https://storage.example.com/signed-upload-url?token=..."
  },
  "charge": {
    "amountCredits": 600,
    "ledgerEntryId": "ledger_abc123"
  }
}

PUT your session.zip file to the upload.url. When you send totalSize, upload is instead a multipart descriptor (id, partSize, and pre-signed parts[].url values).

Error Responses

Returns a signed download URL for the capture's source session.zip archive. For captures with source images, the archive contains the raw keyframe files under keyframes/images/.

Tokens with only reconstruct can download session archives for captures created through the API.

Example Request

curl https://poly.cam/api/v1/captures/550e8400-e29b-41d4-a716-446655440000/session.zip \
  -H "Authorization: Bearer poly_a1b2c3d4e5f6..."

Response 200

{
  "url": "https://storage.example.com/signed-session-zip-url?token=...",
  "expiresIn": 3600
}

Error Responses

Returns a fresh upload target for the capture's session.zip. Use this if the original URL expires or an upload needs to be retried.

Request Body

Optional — send no body for a single PUT URL.

Example Request

curl -X POST https://poly.cam/api/v1/captures/550e8400-e29b-41d4-a716-446655440000/session.zip \
  -H "Authorization: Bearer poly_a1b2c3d4e5f6..."

Response 200

{
  "url": "https://storage.example.com/signed-upload-url?token=..."
}

When totalSize is sent, the response is instead a multipart descriptor (id, partSize, and parts[].url).

Error Responses

Confirms that the capture's session.zip upload has completed. This records the upload metadata and wakes the reconstruction job that was waiting for the file. For single-PUT uploads, Polycam can also confirm server-side when storage reports that the object was created. Multipart uploads must be confirmed with the collected ETag values so Polycam can assemble the final object.

Request Body

Optional — send no body to confirm a single-PUT upload. For a multipart upload, send upload to assemble the parts into the final object.

Example Request

curl -X PUT https://poly.cam/api/v1/captures/550e8400-e29b-41d4-a716-446655440000/session.zip \
  -H "Authorization: Bearer poly_a1b2c3d4e5f6..."

Response 200

{
  "sessionZip": {
    "size": 104857600,
    "timestamp": 1706140800000,
    "md5": "abc123..."
  }
}

Error Responses

Returns current API usage and rate limit status for the workspace associated with the API token.

Example Request

curl https://poly.cam/api/v1/usage \
  -H "Authorization: Bearer poly_a1b2c3d4e5f6..."

Response 200

{
  "reconstruct": {
    "used": 6,
    "limit": 25,
    "remaining": 19,
    "windowHours": 24,
    "resetAt": 1706227200000,
    "concurrent": {
      "active": 1,
      "limit": 2,
      "remaining": 1
    }
  }
}

Response Fields

Error Responses

Simple health check. No authentication required.

curl https://poly.cam/api/v1/health

Response 200

{
  "status": "ok",
  "service": "api-v1"
}