API reference

Projects, publishing, and uploads. Experimental API, currently available in the development environment only.

Version 0.0.0OpenAPI JSON
API status

Experimental developer API for projects, publishing, and uploads. This reference describes the current proof of concept. Production application services are not yet available; use the development environment with a test account. Authentication setup and agent workflows are documented separately.

Base URLhttps://dev-studio.sharekite.app

Using the examples

Requests and responses use JSON unless noted. Set API_ORIGIN to the base URL without a trailing slash. Replace path placeholders and credentials. Save JSON bodies as request.json and binary uploads as file.bin. Examples perform real operations when run.

Authentication

Send Authorization: Bearer ${API_TOKEN} for publisher requests. Byte transfers require the scoped UPLOAD_TOKEN from the upload authorization response instead.

Credentials and permissions

Token variables contain the token without the Bearer prefix. Credentials must also grant the permission listed on each endpoint.

publisherBearer
Publisher API token or OAuth access token. OAuth tokens need the permission listed on each operation. Browser session authentication is outside this developer reference.
uploadBearer
Short-lived upload capability from authorizeUpload. Send its returned authorization header verbatim. Publisher tokens cannot authorize byte transfers.

Projects

Manage project metadata and lifecycle.

List projects

GET/api/projects

List projects in your publishing organisation. Omit archived to list active projects; use true for archived projects or all for both.

Publisher tokenproject:read

Parameters

archivedquery · string
Constraints
{
  "schema": {
    "type": "string",
    "pattern": "^(true|false|all)$"
  },
  "required": false,
  "name": "archived",
  "in": "query"
}
curl example
curl --request GET \
  --header "Authorization: Bearer ${API_TOKEN}" \
  "${API_ORIGIN}/api/projects"

Responses

200OK
projectsarray<object>required
Schema and constraints
{
  "type": "object",
  "properties": {
    "projects": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^[A-Za-z0-9_-]{21}[AQgw]$"
          },
          "organisationId": {
            "type": "string",
            "format": "uuid"
          },
          "privateAudience": {
            "type": "string",
            "enum": [
              "workspace",
              "personal"
            ]
          },
          "name": {
            "type": "string",
            "minLength": 1
          },
          "hostname": {
            "type": "string"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "archived": {
            "type": "boolean"
          },
          "publication": {
            "type": "object",
            "nullable": true,
            "properties": {
              "versionId": {
                "type": "string",
                "pattern": "^[A-Za-z0-9_-]{21}[AQgw]$"
              },
              "versionNumber": {
                "type": "integer",
                "minimum": 0,
                "exclusiveMinimum": true
              },
              "url": {
                "type": "string",
                "format": "uri"
              }
            },
            "required": [
              "versionId",
              "versionNumber",
              "url"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "id",
          "organisationId",
          "privateAudience",
          "name",
          "hostname",
          "createdAt",
          "archived",
          "publication"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "projects"
  ],
  "additionalProperties": false
}
Errors 400 · 401 · 403 · 409 · 500
400Bad Request
errorstringrequired
Allowed: ["invalid_request"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "invalid_request"
      ]
    }
  },
  "required": [
    "error"
  ]
}
401Unauthorized
errorstringrequired
Allowed: ["unauthenticated"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "unauthenticated"
      ]
    }
  },
  "required": [
    "error"
  ]
}
403Forbidden
errorstringrequired
Allowed: ["insufficient_scope"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "insufficient_scope"
      ]
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false
}
409Conflict
errorstringrequired
Allowed: ["organisation_required"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "organisation_required"
      ]
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false
}
500Internal Server Error
errorstringrequired
Allowed: ["internal_error"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "internal_error"
      ]
    }
  },
  "required": [
    "error"
  ]
}

Create a project

POST/api/projects

Create project metadata and assign a hostname. Creating a project does not publish content.

Publisher tokenproject:create

Request body

namestringrequired
Schema and constraints
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1
    }
  },
  "required": [
    "name"
  ],
  "additionalProperties": false,
  "example": {
    "name": "Client report"
  }
}
Example
{
  "name": "Client report"
}
curl example
curl --request POST \
  --header "Authorization: Bearer ${API_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data-binary @request.json \
  "${API_ORIGIN}/api/projects"

Responses

201Created
idstringrequired
organisationIdstring (uuid)required
privateAudiencestringrequired
Allowed: ["workspace","personal"].
namestringrequired
hostnamestringrequired
createdAtstring (date-time)required
archivedbooleanrequired
publicationany | nullrequired
Schema and constraints
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{21}[AQgw]$"
    },
    "organisationId": {
      "type": "string",
      "format": "uuid"
    },
    "privateAudience": {
      "type": "string",
      "enum": [
        "workspace",
        "personal"
      ]
    },
    "name": {
      "type": "string",
      "minLength": 1
    },
    "hostname": {
      "type": "string"
    },
    "createdAt": {
      "type": "string",
      "format": "date-time"
    },
    "archived": {
      "type": "boolean"
    },
    "publication": {
      "nullable": true
    }
  },
  "required": [
    "id",
    "organisationId",
    "privateAudience",
    "name",
    "hostname",
    "createdAt",
    "archived",
    "publication"
  ],
  "additionalProperties": false
}
Errors 400 · 401 · 403 · 409 · 500
400Bad Request
errorstringrequired
Allowed: ["invalid_request"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "invalid_request"
      ]
    }
  },
  "required": [
    "error"
  ]
}
401Unauthorized
errorstringrequired
Allowed: ["unauthenticated"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "unauthenticated"
      ]
    }
  },
  "required": [
    "error"
  ]
}
403Forbidden
errorstringrequired
Allowed: ["insufficient_scope"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "insufficient_scope"
      ]
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false
}
409Conflict
errorstringrequired
Allowed: ["organisation_required","project_limit_reached"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "organisation_required",
        "project_limit_reached"
      ]
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false
}
500Internal Server Error
errorstringrequired
Allowed: ["internal_error"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "internal_error"
      ]
    }
  },
  "required": [
    "error"
  ]
}

Get a project

GET/api/projects/{projectId}

Read project metadata and its current publication, if any.

Publisher tokenproject:read

Parameters

projectIdpath · string · required
Constraints
{
  "schema": {
    "type": "string",
    "pattern": "^[A-Za-z0-9_-]{21}[AQgw]$"
  },
  "required": true,
  "name": "projectId",
  "in": "path"
}
curl example
curl --request GET \
  --header "Authorization: Bearer ${API_TOKEN}" \
  "${API_ORIGIN}/api/projects/{projectId}"

Responses

200OK
idstringrequired
organisationIdstring (uuid)required
privateAudiencestringrequired
Allowed: ["workspace","personal"].
namestringrequired
hostnamestringrequired
createdAtstring (date-time)required
archivedbooleanrequired
publicationobject | nullrequired
Schema and constraints
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{21}[AQgw]$"
    },
    "organisationId": {
      "type": "string",
      "format": "uuid"
    },
    "privateAudience": {
      "type": "string",
      "enum": [
        "workspace",
        "personal"
      ]
    },
    "name": {
      "type": "string",
      "minLength": 1
    },
    "hostname": {
      "type": "string"
    },
    "createdAt": {
      "type": "string",
      "format": "date-time"
    },
    "archived": {
      "type": "boolean"
    },
    "publication": {
      "type": "object",
      "nullable": true,
      "properties": {
        "versionId": {
          "type": "string",
          "pattern": "^[A-Za-z0-9_-]{21}[AQgw]$"
        },
        "versionNumber": {
          "type": "integer",
          "minimum": 0,
          "exclusiveMinimum": true
        },
        "url": {
          "type": "string",
          "format": "uri"
        }
      },
      "required": [
        "versionId",
        "versionNumber",
        "url"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "id",
    "organisationId",
    "privateAudience",
    "name",
    "hostname",
    "createdAt",
    "archived",
    "publication"
  ],
  "additionalProperties": false
}
Errors 400 · 401 · 403 · 404 · 500
400Bad Request
errorstringrequired
Allowed: ["invalid_request"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "invalid_request"
      ]
    }
  },
  "required": [
    "error"
  ]
}
401Unauthorized
errorstringrequired
Allowed: ["unauthenticated"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "unauthenticated"
      ]
    }
  },
  "required": [
    "error"
  ]
}
403Forbidden
errorstringrequired
Allowed: ["insufficient_scope"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "insufficient_scope"
      ]
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false
}
404Not Found
errorstringrequired
Allowed: ["project_not_found"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "project_not_found"
      ]
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false
}
500Internal Server Error
errorstringrequired
Allowed: ["internal_error"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "internal_error"
      ]
    }
  },
  "required": [
    "error"
  ]
}

Update a project

PATCH/api/projects/{projectId}

Change the name, hostname, or archive state. Supply at least one field. The hostname must be a single label under the configured content domain.

Publisher tokenproject:update

Parameters

projectIdpath · string · required
Constraints
{
  "schema": {
    "type": "string",
    "pattern": "^[A-Za-z0-9_-]{21}[AQgw]$"
  },
  "required": true,
  "name": "projectId",
  "in": "path"
}

Request body

namestring
hostnamestring
archivedboolean
Schema and constraints
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1
    },
    "hostname": {
      "type": "string"
    },
    "archived": {
      "type": "boolean"
    }
  },
  "additionalProperties": false
}
curl example
curl --request PATCH \
  --header "Authorization: Bearer ${API_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data-binary @request.json \
  "${API_ORIGIN}/api/projects/{projectId}"

Responses

200OK
idstringrequired
organisationIdstring (uuid)required
privateAudiencestringrequired
Allowed: ["workspace","personal"].
namestringrequired
hostnamestringrequired
createdAtstring (date-time)required
archivedbooleanrequired
publicationobject | nullrequired
Schema and constraints
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{21}[AQgw]$"
    },
    "organisationId": {
      "type": "string",
      "format": "uuid"
    },
    "privateAudience": {
      "type": "string",
      "enum": [
        "workspace",
        "personal"
      ]
    },
    "name": {
      "type": "string",
      "minLength": 1
    },
    "hostname": {
      "type": "string"
    },
    "createdAt": {
      "type": "string",
      "format": "date-time"
    },
    "archived": {
      "type": "boolean"
    },
    "publication": {
      "type": "object",
      "nullable": true,
      "properties": {
        "versionId": {
          "type": "string",
          "pattern": "^[A-Za-z0-9_-]{21}[AQgw]$"
        },
        "versionNumber": {
          "type": "integer",
          "minimum": 0,
          "exclusiveMinimum": true
        },
        "url": {
          "type": "string",
          "format": "uri"
        }
      },
      "required": [
        "versionId",
        "versionNumber",
        "url"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "id",
    "organisationId",
    "privateAudience",
    "name",
    "hostname",
    "createdAt",
    "archived",
    "publication"
  ],
  "additionalProperties": false
}
Errors 400 · 401 · 403 · 404 · 409 · 500 · 503
400Bad Request
errorstringrequired
Allowed: ["invalid_request"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "invalid_request"
      ]
    }
  },
  "required": [
    "error"
  ]
}
401Unauthorized
errorstringrequired
Allowed: ["unauthenticated"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "unauthenticated"
      ]
    }
  },
  "required": [
    "error"
  ]
}
403Forbidden
errorstringrequired
Allowed: ["insufficient_scope"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "insufficient_scope"
      ]
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false
}
404Not Found
errorstringrequired
Allowed: ["project_not_found"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "project_not_found"
      ]
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false
}
409Conflict
errorstringrequired
Allowed: ["hostname_conflict","version_unavailable","publication_conflict","storage_limit_reached"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "hostname_conflict",
        "version_unavailable",
        "publication_conflict",
        "storage_limit_reached"
      ]
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false
}
500Internal Server Error
errorstringrequired
Allowed: ["internal_error"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "internal_error"
      ]
    }
  },
  "required": [
    "error"
  ]
}
503Service Unavailable
errorstringrequired
Allowed: ["hosting_unavailable"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "hosting_unavailable"
      ]
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false
}

Delete a project

DELETE/api/projects/{projectId}

Delete a project and disable its published content. A successful response has no body.

Publisher tokenproject:delete

Parameters

projectIdpath · string · required
Constraints
{
  "schema": {
    "type": "string",
    "pattern": "^[A-Za-z0-9_-]{21}[AQgw]$"
  },
  "required": true,
  "name": "projectId",
  "in": "path"
}
curl example
curl --request DELETE \
  --header "Authorization: Bearer ${API_TOKEN}" \
  "${API_ORIGIN}/api/projects/{projectId}"

Responses

204No Content

No response body.

Errors 400 · 401 · 403 · 404 · 500
400Bad Request
errorstringrequired
Allowed: ["invalid_request"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "invalid_request"
      ]
    }
  },
  "required": [
    "error"
  ]
}
401Unauthorized
errorstringrequired
Allowed: ["unauthenticated"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "unauthenticated"
      ]
    }
  },
  "required": [
    "error"
  ]
}
403Forbidden
errorstringrequired
Allowed: ["insufficient_scope"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "insufficient_scope"
      ]
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false
}
404Not Found
errorstringrequired
Allowed: ["project_not_found"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "project_not_found"
      ]
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false
}
500Internal Server Error
errorstringrequired
Allowed: ["internal_error"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "internal_error"
      ]
    }
  },
  "required": [
    "error"
  ]
}

Publishing

Prepare content and activate versions.

Prepare an inline version

POST/api/projects/{projectId}/versions

Prepare supported text files without publishing them. Use a new versionId and the current version ID as expectedCurrentVersion, or null for the first publication. File paths must be unique. Deletions require baseVersionId and cannot also appear in files. Publish the prepared version in a separate request. Maximum request body: 1048576 bytes.

Publisher tokenproject:publish

Parameters

projectIdpath · string · required
Constraints
{
  "schema": {
    "type": "string",
    "pattern": "^[A-Za-z0-9_-]{21}[AQgw]$"
  },
  "required": true,
  "name": "projectId",
  "in": "path"
}

Request body

versionIdstringrequired
expectedCurrentVersionstring | nullrequired
entrypointstring
baseVersionIdstring
deletedPathsarray<string>
Default: [].
filesarray<object>required
Schema and constraints
{
  "type": "object",
  "properties": {
    "versionId": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{21}[AQgw]$"
    },
    "expectedCurrentVersion": {
      "type": "string",
      "nullable": true,
      "pattern": "^[A-Za-z0-9_-]{21}[AQgw]$"
    },
    "entrypoint": {
      "type": "string",
      "minLength": 1
    },
    "baseVersionId": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{21}[AQgw]$"
    },
    "deletedPaths": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1
      },
      "maxItems": 1000,
      "default": []
    },
    "files": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "path": {
            "type": "string",
            "minLength": 1
          },
          "text": {
            "type": "string"
          }
        },
        "required": [
          "path",
          "text"
        ],
        "additionalProperties": false
      },
      "maxItems": 1000
    }
  },
  "required": [
    "versionId",
    "expectedCurrentVersion",
    "files"
  ],
  "additionalProperties": false,
  "example": {
    "versionId": "AAAAAAAAAAAAAAAAAAAAAA",
    "expectedCurrentVersion": null,
    "files": [
      {
        "path": "index.html",
        "text": "<h1>Client report</h1>"
      }
    ]
  }
}
Example
{
  "versionId": "AAAAAAAAAAAAAAAAAAAAAA",
  "expectedCurrentVersion": null,
  "files": [
    {
      "path": "index.html",
      "text": "<h1>Client report</h1>"
    }
  ]
}
curl example
curl --request POST \
  --header "Authorization: Bearer ${API_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data-binary @request.json \
  "${API_ORIGIN}/api/projects/{projectId}/versions"

Responses

200OK
versionIdstringrequired
versionHashstringrequired
versionNumberintegerrequired
Schema and constraints
{
  "type": "object",
  "properties": {
    "versionId": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{21}[AQgw]$"
    },
    "versionHash": {
      "type": "string"
    },
    "versionNumber": {
      "type": "integer",
      "minimum": 0,
      "exclusiveMinimum": true
    }
  },
  "required": [
    "versionId",
    "versionHash",
    "versionNumber"
  ],
  "additionalProperties": false
}
Errors 400 · 401 · 403 · 404 · 409 · 410 · 413 · 500 · 503
400Bad Request
errorstringrequired
Allowed: ["invalid_request"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "invalid_request"
      ]
    }
  },
  "required": [
    "error"
  ]
}
401Unauthorized
errorstringrequired
Allowed: ["unauthenticated"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "unauthenticated"
      ]
    }
  },
  "required": [
    "error"
  ]
}
403Forbidden
errorstringrequired
Allowed: ["insufficient_scope"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "insufficient_scope"
      ]
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false
}
404Not Found
errorstringrequired
Allowed: ["project_not_found","version_unavailable"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "project_not_found",
        "version_unavailable"
      ]
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false
}
409Conflict
errorstringrequired
Allowed: ["version_conflict"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "version_conflict"
      ]
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false
}
410Gone
errorstringrequired
Allowed: ["upload_expired","upload_cancelled"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "upload_expired",
        "upload_cancelled"
      ]
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false
}
413Payload Too Large
errorstringrequired
Allowed: ["upload_too_large"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "upload_too_large"
      ]
    }
  },
  "required": [
    "error"
  ]
}
500Internal Server Error
errorstringrequired
Allowed: ["internal_error"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "internal_error"
      ]
    }
  },
  "required": [
    "error"
  ]
}
503Service Unavailable
errorstringrequired
Allowed: ["publishing_unavailable"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "publishing_unavailable"
      ]
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false
}

Publish a version

POST/api/projects/{projectId}/versions/{versionId}/publish

Activate a prepared version. Set audience to apply a sharing mode before the version is served; omit it to keep the project's current audience. Setting it needs the change-sharing permission. Set expectedCurrentVersion to the version you intend to replace, or null for the first publication. A publication_conflict response includes the current version ID.

Publisher tokenproject:publish

Parameters

projectIdpath · string · required
Constraints
{
  "schema": {
    "type": "string",
    "pattern": "^[A-Za-z0-9_-]{21}[AQgw]$"
  },
  "required": true,
  "name": "projectId",
  "in": "path"
}
versionIdpath · string · required
Constraints
{
  "schema": {
    "type": "string",
    "pattern": "^[A-Za-z0-9_-]{21}[AQgw]$"
  },
  "required": true,
  "name": "versionId",
  "in": "path"
}

Request body

expectedCurrentVersionstring | nullrequired
audiencestring
Allowed: ["restricted","public"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "expectedCurrentVersion": {
      "type": "string",
      "nullable": true,
      "pattern": "^[A-Za-z0-9_-]{21}[AQgw]$"
    },
    "audience": {
      "type": "string",
      "enum": [
        "restricted",
        "public"
      ]
    }
  },
  "required": [
    "expectedCurrentVersion"
  ],
  "additionalProperties": false,
  "example": {
    "expectedCurrentVersion": null,
    "audience": "public"
  }
}
Example
{
  "expectedCurrentVersion": null,
  "audience": "public"
}
curl example
curl --request POST \
  --header "Authorization: Bearer ${API_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data-binary @request.json \
  "${API_ORIGIN}/api/projects/{projectId}/versions/{versionId}/publish"

Responses

200OK
versionIdstringrequired
versionNumberintegerrequired
urlstring (uri)required
Schema and constraints
{
  "type": "object",
  "properties": {
    "versionId": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{21}[AQgw]$"
    },
    "versionNumber": {
      "type": "integer",
      "minimum": 0,
      "exclusiveMinimum": true
    },
    "url": {
      "type": "string",
      "format": "uri"
    }
  },
  "required": [
    "versionId",
    "versionNumber",
    "url"
  ],
  "additionalProperties": false
}
Errors 400 · 401 · 403 · 404 · 409 · 500 · 503
400Bad Request
errorstringrequired
Allowed: ["invalid_request"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "invalid_request"
      ]
    }
  },
  "required": [
    "error"
  ]
}
401Unauthorized
errorstringrequired
Allowed: ["unauthenticated"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "unauthenticated"
      ]
    }
  },
  "required": [
    "error"
  ]
}
403Forbidden
errorstringrequired
Allowed: ["insufficient_scope"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "insufficient_scope"
      ]
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false
}
404Not Found
errorstringrequired
Allowed: ["project_not_found","version_unavailable"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "project_not_found",
        "version_unavailable"
      ]
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false
}
409Conflict

object | object

Schema and constraints
{
  "anyOf": [
    {
      "type": "object",
      "properties": {
        "error": {
          "type": "string",
          "enum": [
            "publication_conflict"
          ]
        },
        "currentVersionId": {
          "type": "string",
          "nullable": true,
          "pattern": "^[A-Za-z0-9_-]{21}[AQgw]$"
        }
      },
      "required": [
        "error",
        "currentVersionId"
      ],
      "additionalProperties": false
    },
    {
      "type": "object",
      "properties": {
        "error": {
          "type": "string",
          "enum": [
            "project_archived",
            "storage_limit_reached"
          ]
        }
      },
      "required": [
        "error"
      ],
      "additionalProperties": false
    }
  ]
}
500Internal Server Error
errorstringrequired
Allowed: ["internal_error"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "internal_error"
      ]
    }
  },
  "required": [
    "error"
  ]
}
503Service Unavailable
errorstringrequired
Allowed: ["publishing_unavailable"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "publishing_unavailable"
      ]
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false
}

Uploads

Transfer files and ZIP archives with scoped capabilities.

Create an upload

POST/api/projects/{projectId}/uploads

Declare either files or archiveSize, not both. Use unique file paths and a new versionId. Deletions require baseVersionId and cannot overlap uploaded paths. For a full file upload, provide an existing entrypoint, index.html, or a single file. Complete all transfers before publishing the prepared version.

Publisher tokenproject:publish

Parameters

projectIdpath · string · required
Constraints
{
  "schema": {
    "type": "string",
    "pattern": "^[A-Za-z0-9_-]{21}[AQgw]$"
  },
  "required": true,
  "name": "projectId",
  "in": "path"
}

Request body

versionIdstringrequired
expectedCurrentVersionstring | nullrequired
entrypointstring
baseVersionIdstring
deletedPathsarray<string>
Default: [].
filesarray<object>
archiveSizeinteger
Schema and constraints
{
  "type": "object",
  "properties": {
    "versionId": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{21}[AQgw]$"
    },
    "expectedCurrentVersion": {
      "type": "string",
      "nullable": true,
      "pattern": "^[A-Za-z0-9_-]{21}[AQgw]$"
    },
    "entrypoint": {
      "type": "string",
      "minLength": 1
    },
    "baseVersionId": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{21}[AQgw]$"
    },
    "deletedPaths": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1
      },
      "maxItems": 1000,
      "default": []
    },
    "files": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "path": {
            "type": "string",
            "minLength": 1
          },
          "size": {
            "type": "integer",
            "minimum": 0,
            "maximum": 20971520
          }
        },
        "required": [
          "path",
          "size"
        ],
        "additionalProperties": false
      },
      "maxItems": 1000
    },
    "archiveSize": {
      "type": "integer",
      "minimum": 0,
      "maximum": 52428800
    }
  },
  "required": [
    "versionId",
    "expectedCurrentVersion"
  ],
  "additionalProperties": false,
  "example": {
    "versionId": "AAAAAAAAAAAAAAAAAAAAAA",
    "expectedCurrentVersion": null,
    "files": [
      {
        "path": "index.html",
        "size": 22
      }
    ]
  }
}
Example
{
  "versionId": "AAAAAAAAAAAAAAAAAAAAAA",
  "expectedCurrentVersion": null,
  "files": [
    {
      "path": "index.html",
      "size": 22
    }
  ]
}
curl example
curl --request POST \
  --header "Authorization: Bearer ${API_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data-binary @request.json \
  "${API_ORIGIN}/api/projects/{projectId}/uploads"

Responses

201Created
idstringrequired
expiresAtstring (date-time)required
cancelledbooleanrequired
filesarray<object>required
archiveobject | nullrequired
versionobject | nullrequired
Schema and constraints
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{21}[AQgw]$"
    },
    "expiresAt": {
      "type": "string",
      "format": "date-time"
    },
    "cancelled": {
      "type": "boolean"
    },
    "files": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "path": {
            "type": "string",
            "minLength": 1
          },
          "size": {
            "type": "integer",
            "minimum": 0,
            "maximum": 20971520
          },
          "id": {
            "type": "string",
            "pattern": "^[A-Za-z0-9_-]{21}[AQgw]$"
          },
          "complete": {
            "type": "boolean"
          }
        },
        "required": [
          "path",
          "size",
          "id",
          "complete"
        ],
        "additionalProperties": false
      }
    },
    "archive": {
      "type": "object",
      "nullable": true,
      "properties": {
        "size": {
          "type": "integer",
          "minimum": 0
        },
        "complete": {
          "type": "boolean"
        }
      },
      "required": [
        "size",
        "complete"
      ],
      "additionalProperties": false
    },
    "version": {
      "type": "object",
      "nullable": true,
      "properties": {
        "versionId": {
          "type": "string",
          "pattern": "^[A-Za-z0-9_-]{21}[AQgw]$"
        }
      },
      "required": [
        "versionId"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "id",
    "expiresAt",
    "cancelled",
    "files",
    "archive",
    "version"
  ],
  "additionalProperties": false
}
Errors 400 · 401 · 403 · 404 · 409 · 410 · 500 · 503
400Bad Request
errorstringrequired
Allowed: ["invalid_request"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "invalid_request"
      ]
    }
  },
  "required": [
    "error"
  ]
}
401Unauthorized
errorstringrequired
Allowed: ["unauthenticated"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "unauthenticated"
      ]
    }
  },
  "required": [
    "error"
  ]
}
403Forbidden
errorstringrequired
Allowed: ["insufficient_scope"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "insufficient_scope"
      ]
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false
}
404Not Found
errorstringrequired
Allowed: ["project_not_found","upload_not_found","version_unavailable"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "project_not_found",
        "upload_not_found",
        "version_unavailable"
      ]
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false
}
409Conflict
errorstringrequired
Allowed: ["version_conflict","upload_limit_reached"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "version_conflict",
        "upload_limit_reached"
      ]
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false
}
410Gone
errorstringrequired
Allowed: ["upload_expired","upload_cancelled"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "upload_expired",
        "upload_cancelled"
      ]
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false
}
500Internal Server Error
errorstringrequired
Allowed: ["internal_error"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "internal_error"
      ]
    }
  },
  "required": [
    "error"
  ]
}
503Service Unavailable
errorstringrequired
Allowed: ["preparation_unavailable"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "preparation_unavailable"
      ]
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false
}

Get an upload

GET/api/projects/{projectId}/uploads/{sessionId}

Read transfer completion, expiry, cancellation, and prepared version state.

Publisher tokenproject:read

Parameters

projectIdpath · string · required
Constraints
{
  "schema": {
    "type": "string",
    "pattern": "^[A-Za-z0-9_-]{21}[AQgw]$"
  },
  "required": true,
  "name": "projectId",
  "in": "path"
}
sessionIdpath · string · required
Constraints
{
  "schema": {
    "type": "string",
    "pattern": "^[A-Za-z0-9_-]{21}[AQgw]$"
  },
  "required": true,
  "name": "sessionId",
  "in": "path"
}
curl example
curl --request GET \
  --header "Authorization: Bearer ${API_TOKEN}" \
  "${API_ORIGIN}/api/projects/{projectId}/uploads/{sessionId}"

Responses

200OK
idstringrequired
expiresAtstring (date-time)required
cancelledbooleanrequired
filesarray<object>required
archiveobject | nullrequired
versionobject | nullrequired
Schema and constraints
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{21}[AQgw]$"
    },
    "expiresAt": {
      "type": "string",
      "format": "date-time"
    },
    "cancelled": {
      "type": "boolean"
    },
    "files": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "path": {
            "type": "string",
            "minLength": 1
          },
          "size": {
            "type": "integer",
            "minimum": 0,
            "maximum": 20971520
          },
          "id": {
            "type": "string",
            "pattern": "^[A-Za-z0-9_-]{21}[AQgw]$"
          },
          "complete": {
            "type": "boolean"
          }
        },
        "required": [
          "path",
          "size",
          "id",
          "complete"
        ],
        "additionalProperties": false
      }
    },
    "archive": {
      "type": "object",
      "nullable": true,
      "properties": {
        "size": {
          "type": "integer",
          "minimum": 0
        },
        "complete": {
          "type": "boolean"
        }
      },
      "required": [
        "size",
        "complete"
      ],
      "additionalProperties": false
    },
    "version": {
      "type": "object",
      "nullable": true,
      "properties": {
        "versionId": {
          "type": "string",
          "pattern": "^[A-Za-z0-9_-]{21}[AQgw]$"
        }
      },
      "required": [
        "versionId"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "id",
    "expiresAt",
    "cancelled",
    "files",
    "archive",
    "version"
  ],
  "additionalProperties": false
}
Errors 400 · 401 · 403 · 404 · 500 · 503
400Bad Request
errorstringrequired
Allowed: ["invalid_request"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "invalid_request"
      ]
    }
  },
  "required": [
    "error"
  ]
}
401Unauthorized
errorstringrequired
Allowed: ["unauthenticated"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "unauthenticated"
      ]
    }
  },
  "required": [
    "error"
  ]
}
403Forbidden
errorstringrequired
Allowed: ["insufficient_scope"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "insufficient_scope"
      ]
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false
}
404Not Found
errorstringrequired
Allowed: ["project_not_found","upload_not_found","version_unavailable"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "project_not_found",
        "upload_not_found",
        "version_unavailable"
      ]
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false
}
500Internal Server Error
errorstringrequired
Allowed: ["internal_error"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "internal_error"
      ]
    }
  },
  "required": [
    "error"
  ]
}
503Service Unavailable
errorstringrequired
Allowed: ["preparation_unavailable"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "preparation_unavailable"
      ]
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false
}

Authorize transfers

POST/api/projects/{projectId}/uploads/{sessionId}/authorization

Issue a short-lived upload capability. Use the returned authorization header for file and archive transfers, not your publisher token. Transfers currently use the same Platform origin.

Publisher tokenproject:publish

Parameters

projectIdpath · string · required
Constraints
{
  "schema": {
    "type": "string",
    "pattern": "^[A-Za-z0-9_-]{21}[AQgw]$"
  },
  "required": true,
  "name": "projectId",
  "in": "path"
}
sessionIdpath · string · required
Constraints
{
  "schema": {
    "type": "string",
    "pattern": "^[A-Za-z0-9_-]{21}[AQgw]$"
  },
  "required": true,
  "name": "sessionId",
  "in": "path"
}

Request body

object

Schema and constraints
{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}
curl example
curl --request POST \
  --header "Authorization: Bearer ${API_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data-binary @request.json \
  "${API_ORIGIN}/api/projects/{projectId}/uploads/{sessionId}/authorization"

Responses

200OK
headersobjectrequired
expiresAtstring (date-time)required
Schema and constraints
{
  "type": "object",
  "properties": {
    "headers": {
      "type": "object",
      "properties": {
        "authorization": {
          "type": "string"
        }
      },
      "required": [
        "authorization"
      ],
      "additionalProperties": false
    },
    "expiresAt": {
      "type": "string",
      "format": "date-time"
    }
  },
  "required": [
    "headers",
    "expiresAt"
  ],
  "additionalProperties": false
}
Errors 400 · 401 · 403 · 404 · 410 · 500
400Bad Request
errorstringrequired
Allowed: ["invalid_request"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "invalid_request"
      ]
    }
  },
  "required": [
    "error"
  ]
}
401Unauthorized
errorstringrequired
Allowed: ["unauthenticated"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "unauthenticated"
      ]
    }
  },
  "required": [
    "error"
  ]
}
403Forbidden
errorstringrequired
Allowed: ["insufficient_scope"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "insufficient_scope"
      ]
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false
}
404Not Found
errorstringrequired
Allowed: ["project_not_found","upload_not_found","version_unavailable"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "project_not_found",
        "upload_not_found",
        "version_unavailable"
      ]
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false
}
410Gone
errorstringrequired
Allowed: ["upload_expired","upload_cancelled"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "upload_expired",
        "upload_cancelled"
      ]
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false
}
500Internal Server Error
errorstringrequired
Allowed: ["internal_error"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "internal_error"
      ]
    }
  },
  "required": [
    "error"
  ]
}

Cancel an upload

POST/api/projects/{projectId}/uploads/{sessionId}/cancel

Cancel an upload session. Further transfers with this session are rejected.

Publisher tokenproject:publish

Parameters

projectIdpath · string · required
Constraints
{
  "schema": {
    "type": "string",
    "pattern": "^[A-Za-z0-9_-]{21}[AQgw]$"
  },
  "required": true,
  "name": "projectId",
  "in": "path"
}
sessionIdpath · string · required
Constraints
{
  "schema": {
    "type": "string",
    "pattern": "^[A-Za-z0-9_-]{21}[AQgw]$"
  },
  "required": true,
  "name": "sessionId",
  "in": "path"
}

Request body

object

Schema and constraints
{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}
curl example
curl --request POST \
  --header "Authorization: Bearer ${API_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data-binary @request.json \
  "${API_ORIGIN}/api/projects/{projectId}/uploads/{sessionId}/cancel"

Responses

200OK
cancelledbooleanrequired
Allowed: [true].
Schema and constraints
{
  "type": "object",
  "properties": {
    "cancelled": {
      "type": "boolean",
      "enum": [
        true
      ]
    }
  },
  "required": [
    "cancelled"
  ],
  "additionalProperties": false
}
Errors 400 · 401 · 403 · 404 · 500
400Bad Request
errorstringrequired
Allowed: ["invalid_request"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "invalid_request"
      ]
    }
  },
  "required": [
    "error"
  ]
}
401Unauthorized
errorstringrequired
Allowed: ["unauthenticated"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "unauthenticated"
      ]
    }
  },
  "required": [
    "error"
  ]
}
403Forbidden
errorstringrequired
Allowed: ["insufficient_scope"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "insufficient_scope"
      ]
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false
}
404Not Found
errorstringrequired
Allowed: ["project_not_found","upload_not_found","version_unavailable"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "project_not_found",
        "upload_not_found",
        "version_unavailable"
      ]
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false
}
500Internal Server Error
errorstringrequired
Allowed: ["internal_error"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "internal_error"
      ]
    }
  },
  "required": [
    "error"
  ]
}

Upload a file

PUT/api/projects/{projectId}/uploads/{sessionId}/files/{fileId}

Send the declared file bytes as application/octet-stream using the upload authorization header. Use the file ID returned by the upload session. Interrupted files must be sent again in full. Maximum request body: 20971520 bytes.

Upload token

Parameters

projectIdpath · string · required
Constraints
{
  "schema": {
    "type": "string",
    "pattern": "^[A-Za-z0-9_-]{21}[AQgw]$"
  },
  "required": true,
  "name": "projectId",
  "in": "path"
}
sessionIdpath · string · required
Constraints
{
  "schema": {
    "type": "string",
    "pattern": "^[A-Za-z0-9_-]{21}[AQgw]$"
  },
  "required": true,
  "name": "sessionId",
  "in": "path"
}
fileIdpath · string · required
Constraints
{
  "schema": {
    "type": "string",
    "pattern": "^[A-Za-z0-9_-]{21}[AQgw]$"
  },
  "required": true,
  "name": "fileId",
  "in": "path"
}

Request body

application/octet-stream

string (binary)

Schema and constraints
{
  "type": "string",
  "format": "binary"
}
curl example
curl --request PUT \
  --header "Authorization: Bearer ${UPLOAD_TOKEN}" \
  --header 'Content-Type: application/octet-stream' \
  --data-binary @file.bin \
  "${API_ORIGIN}/api/projects/{projectId}/uploads/{sessionId}/files/{fileId}"

Responses

200OK
idstringrequired
expiresAtstring (date-time)required
cancelledbooleanrequired
filesarray<object>required
archiveobject | nullrequired
versionobject | nullrequired
Schema and constraints
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{21}[AQgw]$"
    },
    "expiresAt": {
      "type": "string",
      "format": "date-time"
    },
    "cancelled": {
      "type": "boolean"
    },
    "files": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "path": {
            "type": "string",
            "minLength": 1
          },
          "size": {
            "type": "integer",
            "minimum": 0,
            "maximum": 20971520
          },
          "id": {
            "type": "string",
            "pattern": "^[A-Za-z0-9_-]{21}[AQgw]$"
          },
          "complete": {
            "type": "boolean"
          }
        },
        "required": [
          "path",
          "size",
          "id",
          "complete"
        ],
        "additionalProperties": false
      }
    },
    "archive": {
      "type": "object",
      "nullable": true,
      "properties": {
        "size": {
          "type": "integer",
          "minimum": 0
        },
        "complete": {
          "type": "boolean"
        }
      },
      "required": [
        "size",
        "complete"
      ],
      "additionalProperties": false
    },
    "version": {
      "type": "object",
      "nullable": true,
      "properties": {
        "versionId": {
          "type": "string",
          "pattern": "^[A-Za-z0-9_-]{21}[AQgw]$"
        }
      },
      "required": [
        "versionId"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "id",
    "expiresAt",
    "cancelled",
    "files",
    "archive",
    "version"
  ],
  "additionalProperties": false
}
Errors 400 · 401 · 403 · 404 · 410 · 413 · 500 · 503
400Bad Request
errorstringrequired
Allowed: ["invalid_request"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "invalid_request"
      ]
    }
  },
  "required": [
    "error"
  ]
}
401Unauthorized
errorstringrequired
Allowed: ["unauthenticated"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "unauthenticated"
      ]
    }
  },
  "required": [
    "error"
  ]
}
403Forbidden
errorstringrequired
Allowed: ["insufficient_scope"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "insufficient_scope"
      ]
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false
}
404Not Found
errorstringrequired
Allowed: ["project_not_found","upload_not_found","version_unavailable"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "project_not_found",
        "upload_not_found",
        "version_unavailable"
      ]
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false
}
410Gone
errorstringrequired
Allowed: ["upload_expired","upload_cancelled"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "upload_expired",
        "upload_cancelled"
      ]
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false
}
413Payload Too Large
errorstringrequired
Allowed: ["upload_too_large"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "upload_too_large"
      ]
    }
  },
  "required": [
    "error"
  ]
}
500Internal Server Error
errorstringrequired
Allowed: ["internal_error"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "internal_error"
      ]
    }
  },
  "required": [
    "error"
  ]
}
503Service Unavailable
errorstringrequired
Allowed: ["preparation_unavailable"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "preparation_unavailable"
      ]
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false
}

Upload a ZIP archive

PUT/api/projects/{projectId}/uploads/{sessionId}/archive

Send the declared ZIP bytes as application/octet-stream using the upload authorization header. Preparation validates the archive before the version can be published. Maximum request body: 52428800 bytes.

Upload token

Parameters

projectIdpath · string · required
Constraints
{
  "schema": {
    "type": "string",
    "pattern": "^[A-Za-z0-9_-]{21}[AQgw]$"
  },
  "required": true,
  "name": "projectId",
  "in": "path"
}
sessionIdpath · string · required
Constraints
{
  "schema": {
    "type": "string",
    "pattern": "^[A-Za-z0-9_-]{21}[AQgw]$"
  },
  "required": true,
  "name": "sessionId",
  "in": "path"
}

Request body

application/octet-stream

string (binary)

Schema and constraints
{
  "type": "string",
  "format": "binary"
}
curl example
curl --request PUT \
  --header "Authorization: Bearer ${UPLOAD_TOKEN}" \
  --header 'Content-Type: application/octet-stream' \
  --data-binary @file.bin \
  "${API_ORIGIN}/api/projects/{projectId}/uploads/{sessionId}/archive"

Responses

200OK
idstringrequired
expiresAtstring (date-time)required
cancelledbooleanrequired
filesarray<object>required
archiveobject | nullrequired
versionobject | nullrequired
Schema and constraints
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{21}[AQgw]$"
    },
    "expiresAt": {
      "type": "string",
      "format": "date-time"
    },
    "cancelled": {
      "type": "boolean"
    },
    "files": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "path": {
            "type": "string",
            "minLength": 1
          },
          "size": {
            "type": "integer",
            "minimum": 0,
            "maximum": 20971520
          },
          "id": {
            "type": "string",
            "pattern": "^[A-Za-z0-9_-]{21}[AQgw]$"
          },
          "complete": {
            "type": "boolean"
          }
        },
        "required": [
          "path",
          "size",
          "id",
          "complete"
        ],
        "additionalProperties": false
      }
    },
    "archive": {
      "type": "object",
      "nullable": true,
      "properties": {
        "size": {
          "type": "integer",
          "minimum": 0
        },
        "complete": {
          "type": "boolean"
        }
      },
      "required": [
        "size",
        "complete"
      ],
      "additionalProperties": false
    },
    "version": {
      "type": "object",
      "nullable": true,
      "properties": {
        "versionId": {
          "type": "string",
          "pattern": "^[A-Za-z0-9_-]{21}[AQgw]$"
        }
      },
      "required": [
        "versionId"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "id",
    "expiresAt",
    "cancelled",
    "files",
    "archive",
    "version"
  ],
  "additionalProperties": false
}
Errors 400 · 401 · 403 · 404 · 410 · 413 · 500 · 503
400Bad Request
errorstringrequired
Allowed: ["invalid_request"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "invalid_request"
      ]
    }
  },
  "required": [
    "error"
  ]
}
401Unauthorized
errorstringrequired
Allowed: ["unauthenticated"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "unauthenticated"
      ]
    }
  },
  "required": [
    "error"
  ]
}
403Forbidden
errorstringrequired
Allowed: ["insufficient_scope"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "insufficient_scope"
      ]
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false
}
404Not Found
errorstringrequired
Allowed: ["project_not_found","upload_not_found","version_unavailable"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "project_not_found",
        "upload_not_found",
        "version_unavailable"
      ]
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false
}
410Gone
errorstringrequired
Allowed: ["upload_expired","upload_cancelled"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "upload_expired",
        "upload_cancelled"
      ]
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false
}
413Payload Too Large
errorstringrequired
Allowed: ["upload_too_large"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "upload_too_large"
      ]
    }
  },
  "required": [
    "error"
  ]
}
500Internal Server Error
errorstringrequired
Allowed: ["internal_error"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "internal_error"
      ]
    }
  },
  "required": [
    "error"
  ]
}
503Service Unavailable
errorstringrequired
Allowed: ["preparation_unavailable"].
Schema and constraints
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "preparation_unavailable"
      ]
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false
}