{ "openapi": "3.0.0", "info": { "title": "Sharekite API", "version": "0.0.0", "description": "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." }, "servers": [ { "url": "https://dev-studio.sharekite.app", "description": "Cloud development (synthetic test data only)" } ], "tags": [ { "name": "Projects", "description": "Manage project metadata and lifecycle." }, { "name": "Publishing", "description": "Prepare content and activate versions." }, { "name": "Uploads", "description": "Transfer files and ZIP archives with scoped capabilities." } ], "components": { "securitySchemes": { "publisherBearer": { "type": "http", "scheme": "bearer", "description": "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": { "type": "http", "scheme": "bearer", "description": "Short-lived upload capability from authorizeUpload. Send its returned authorization header verbatim. Publisher tokens cannot authorize byte transfers." } }, "schemas": {}, "parameters": {} }, "paths": { "/api/projects": { "get": { "operationId": "listProjects", "summary": "List projects", "tags": [ "Projects" ], "description": "List projects in your publishing organisation. Omit archived to list active projects; use true for archived projects or all for both.\n\nAccess: publisher with project:read", "security": [ { "publisherBearer": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^(true|false|all)$" }, "required": false, "name": "archived", "in": "query" } ], "responses": { "200": { "description": "HTTP 200", "content": { "application/json": { "schema": { "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 } } } }, "400": { "description": "HTTP 400", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "invalid_request" ] } }, "required": [ "error" ] } } } }, "401": { "description": "HTTP 401", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "unauthenticated" ] } }, "required": [ "error" ] } } } }, "403": { "description": "HTTP 403", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "insufficient_scope" ] } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "HTTP 409", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "organisation_required" ] } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "HTTP 500", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "internal_error" ] } }, "required": [ "error" ] } } } } } }, "post": { "operationId": "createProject", "summary": "Create a project", "tags": [ "Projects" ], "description": "Create project metadata and assign a hostname. Creating a project does not publish content.\n\nAccess: publisher with project:create", "security": [ { "publisherBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 } }, "required": [ "name" ], "additionalProperties": false, "example": { "name": "Client report" } } } } }, "responses": { "201": { "description": "HTTP 201", "content": { "application/json": { "schema": { "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 } } } }, "400": { "description": "HTTP 400", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "invalid_request" ] } }, "required": [ "error" ] } } } }, "401": { "description": "HTTP 401", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "unauthenticated" ] } }, "required": [ "error" ] } } } }, "403": { "description": "HTTP 403", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "insufficient_scope" ] } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "HTTP 409", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "organisation_required", "project_limit_reached" ] } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "HTTP 500", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "internal_error" ] } }, "required": [ "error" ] } } } } } } }, "/api/projects/{projectId}": { "get": { "operationId": "getProject", "summary": "Get a project", "tags": [ "Projects" ], "description": "Read project metadata and its current publication, if any.\n\nAccess: publisher with project:read", "security": [ { "publisherBearer": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{21}[AQgw]$" }, "required": true, "name": "projectId", "in": "path" } ], "responses": { "200": { "description": "HTTP 200", "content": { "application/json": { "schema": { "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 } } } }, "400": { "description": "HTTP 400", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "invalid_request" ] } }, "required": [ "error" ] } } } }, "401": { "description": "HTTP 401", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "unauthenticated" ] } }, "required": [ "error" ] } } } }, "403": { "description": "HTTP 403", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "insufficient_scope" ] } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "HTTP 404", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "project_not_found" ] } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "HTTP 500", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "internal_error" ] } }, "required": [ "error" ] } } } } } }, "patch": { "operationId": "updateProject", "summary": "Update a project", "tags": [ "Projects" ], "description": "Change the name, hostname, or archive state. Supply at least one field. The hostname must be a single label under the configured content domain.\n\nAccess: publisher with project:update", "security": [ { "publisherBearer": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{21}[AQgw]$" }, "required": true, "name": "projectId", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "hostname": { "type": "string" }, "archived": { "type": "boolean" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "HTTP 200", "content": { "application/json": { "schema": { "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 } } } }, "400": { "description": "HTTP 400", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "invalid_request" ] } }, "required": [ "error" ] } } } }, "401": { "description": "HTTP 401", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "unauthenticated" ] } }, "required": [ "error" ] } } } }, "403": { "description": "HTTP 403", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "insufficient_scope" ] } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "HTTP 404", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "project_not_found" ] } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "HTTP 409", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "hostname_conflict", "version_unavailable", "publication_conflict", "storage_limit_reached" ] } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "HTTP 500", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "internal_error" ] } }, "required": [ "error" ] } } } }, "503": { "description": "HTTP 503", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "hosting_unavailable" ] } }, "required": [ "error" ], "additionalProperties": false } } } } } }, "delete": { "operationId": "deleteProject", "summary": "Delete a project", "tags": [ "Projects" ], "description": "Delete a project and disable its published content. A successful response has no body.\n\nAccess: publisher with project:delete", "security": [ { "publisherBearer": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{21}[AQgw]$" }, "required": true, "name": "projectId", "in": "path" } ], "responses": { "204": { "description": "HTTP 204", "headers": {} }, "400": { "description": "HTTP 400", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "invalid_request" ] } }, "required": [ "error" ] } } } }, "401": { "description": "HTTP 401", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "unauthenticated" ] } }, "required": [ "error" ] } } } }, "403": { "description": "HTTP 403", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "insufficient_scope" ] } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "HTTP 404", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "project_not_found" ] } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "HTTP 500", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "internal_error" ] } }, "required": [ "error" ] } } } } } } }, "/api/projects/{projectId}/versions": { "post": { "operationId": "prepareInline", "summary": "Prepare an inline version", "tags": [ "Publishing" ], "description": "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.\n\nAccess: publisher with project:publish\n\nMaximum request body: 1048576 bytes.", "security": [ { "publisherBearer": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{21}[AQgw]$" }, "required": true, "name": "projectId", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "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": "

Client report

" } ] } } } } }, "responses": { "200": { "description": "HTTP 200", "content": { "application/json": { "schema": { "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 } } } }, "400": { "description": "HTTP 400", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "invalid_request" ] } }, "required": [ "error" ] } } } }, "401": { "description": "HTTP 401", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "unauthenticated" ] } }, "required": [ "error" ] } } } }, "403": { "description": "HTTP 403", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "insufficient_scope" ] } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "HTTP 404", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "project_not_found", "version_unavailable" ] } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "HTTP 409", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "version_conflict" ] } }, "required": [ "error" ], "additionalProperties": false } } } }, "410": { "description": "HTTP 410", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "upload_expired", "upload_cancelled" ] } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "HTTP 413", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "upload_too_large" ] } }, "required": [ "error" ] } } } }, "500": { "description": "HTTP 500", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "internal_error" ] } }, "required": [ "error" ] } } } }, "503": { "description": "HTTP 503", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "publishing_unavailable" ] } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/api/projects/{projectId}/versions/{versionId}/publish": { "post": { "operationId": "publishVersion", "summary": "Publish a version", "tags": [ "Publishing" ], "description": "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.\n\nAccess: publisher with project:publish", "security": [ { "publisherBearer": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{21}[AQgw]$" }, "required": true, "name": "projectId", "in": "path" }, { "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{21}[AQgw]$" }, "required": true, "name": "versionId", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "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" } } } } }, "responses": { "200": { "description": "HTTP 200", "content": { "application/json": { "schema": { "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 } } } }, "400": { "description": "HTTP 400", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "invalid_request" ] } }, "required": [ "error" ] } } } }, "401": { "description": "HTTP 401", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "unauthenticated" ] } }, "required": [ "error" ] } } } }, "403": { "description": "HTTP 403", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "insufficient_scope" ] } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "HTTP 404", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "project_not_found", "version_unavailable" ] } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "HTTP 409", "content": { "application/json": { "schema": { "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 } ] } } } }, "500": { "description": "HTTP 500", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "internal_error" ] } }, "required": [ "error" ] } } } }, "503": { "description": "HTTP 503", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "publishing_unavailable" ] } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/api/projects/{projectId}/uploads": { "post": { "operationId": "createUpload", "summary": "Create an upload", "tags": [ "Uploads" ], "description": "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.\n\nAccess: publisher with project:publish", "security": [ { "publisherBearer": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{21}[AQgw]$" }, "required": true, "name": "projectId", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "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 } ] } } } } }, "responses": { "201": { "description": "HTTP 201", "content": { "application/json": { "schema": { "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 } } } }, "400": { "description": "HTTP 400", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "invalid_request" ] } }, "required": [ "error" ] } } } }, "401": { "description": "HTTP 401", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "unauthenticated" ] } }, "required": [ "error" ] } } } }, "403": { "description": "HTTP 403", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "insufficient_scope" ] } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "HTTP 404", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "project_not_found", "upload_not_found", "version_unavailable" ] } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "HTTP 409", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "version_conflict", "upload_limit_reached" ] } }, "required": [ "error" ], "additionalProperties": false } } } }, "410": { "description": "HTTP 410", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "upload_expired", "upload_cancelled" ] } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "HTTP 500", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "internal_error" ] } }, "required": [ "error" ] } } } }, "503": { "description": "HTTP 503", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "preparation_unavailable" ] } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/api/projects/{projectId}/uploads/{sessionId}": { "get": { "operationId": "getUpload", "summary": "Get an upload", "tags": [ "Uploads" ], "description": "Read transfer completion, expiry, cancellation, and prepared version state.\n\nAccess: publisher with project:read", "security": [ { "publisherBearer": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{21}[AQgw]$" }, "required": true, "name": "projectId", "in": "path" }, { "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{21}[AQgw]$" }, "required": true, "name": "sessionId", "in": "path" } ], "responses": { "200": { "description": "HTTP 200", "content": { "application/json": { "schema": { "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 } } } }, "400": { "description": "HTTP 400", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "invalid_request" ] } }, "required": [ "error" ] } } } }, "401": { "description": "HTTP 401", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "unauthenticated" ] } }, "required": [ "error" ] } } } }, "403": { "description": "HTTP 403", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "insufficient_scope" ] } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "HTTP 404", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "project_not_found", "upload_not_found", "version_unavailable" ] } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "HTTP 500", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "internal_error" ] } }, "required": [ "error" ] } } } }, "503": { "description": "HTTP 503", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "preparation_unavailable" ] } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/api/projects/{projectId}/uploads/{sessionId}/authorization": { "post": { "operationId": "authorizeUpload", "summary": "Authorize transfers", "tags": [ "Uploads" ], "description": "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.\n\nAccess: publisher with project:publish", "security": [ { "publisherBearer": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{21}[AQgw]$" }, "required": true, "name": "projectId", "in": "path" }, { "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{21}[AQgw]$" }, "required": true, "name": "sessionId", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "responses": { "200": { "description": "HTTP 200", "content": { "application/json": { "schema": { "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 } } } }, "400": { "description": "HTTP 400", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "invalid_request" ] } }, "required": [ "error" ] } } } }, "401": { "description": "HTTP 401", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "unauthenticated" ] } }, "required": [ "error" ] } } } }, "403": { "description": "HTTP 403", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "insufficient_scope" ] } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "HTTP 404", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "project_not_found", "upload_not_found", "version_unavailable" ] } }, "required": [ "error" ], "additionalProperties": false } } } }, "410": { "description": "HTTP 410", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "upload_expired", "upload_cancelled" ] } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "HTTP 500", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "internal_error" ] } }, "required": [ "error" ] } } } } } } }, "/api/projects/{projectId}/uploads/{sessionId}/cancel": { "post": { "operationId": "cancelUpload", "summary": "Cancel an upload", "tags": [ "Uploads" ], "description": "Cancel an upload session. Further transfers with this session are rejected.\n\nAccess: publisher with project:publish", "security": [ { "publisherBearer": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{21}[AQgw]$" }, "required": true, "name": "projectId", "in": "path" }, { "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{21}[AQgw]$" }, "required": true, "name": "sessionId", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "responses": { "200": { "description": "HTTP 200", "content": { "application/json": { "schema": { "type": "object", "properties": { "cancelled": { "type": "boolean", "enum": [ true ] } }, "required": [ "cancelled" ], "additionalProperties": false } } } }, "400": { "description": "HTTP 400", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "invalid_request" ] } }, "required": [ "error" ] } } } }, "401": { "description": "HTTP 401", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "unauthenticated" ] } }, "required": [ "error" ] } } } }, "403": { "description": "HTTP 403", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "insufficient_scope" ] } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "HTTP 404", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "project_not_found", "upload_not_found", "version_unavailable" ] } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "HTTP 500", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "internal_error" ] } }, "required": [ "error" ] } } } } } } }, "/api/projects/{projectId}/uploads/{sessionId}/files/{fileId}": { "put": { "operationId": "uploadFile", "summary": "Upload a file", "tags": [ "Uploads" ], "description": "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.\n\nAccess: uploader\n\nMaximum request body: 20971520 bytes.", "security": [ { "uploadBearer": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{21}[AQgw]$" }, "required": true, "name": "projectId", "in": "path" }, { "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{21}[AQgw]$" }, "required": true, "name": "sessionId", "in": "path" }, { "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{21}[AQgw]$" }, "required": true, "name": "fileId", "in": "path" } ], "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "responses": { "200": { "description": "HTTP 200", "content": { "application/json": { "schema": { "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 } } } }, "400": { "description": "HTTP 400", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "invalid_request" ] } }, "required": [ "error" ] } } } }, "401": { "description": "HTTP 401", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "unauthenticated" ] } }, "required": [ "error" ] } } } }, "403": { "description": "HTTP 403", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "insufficient_scope" ] } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "HTTP 404", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "project_not_found", "upload_not_found", "version_unavailable" ] } }, "required": [ "error" ], "additionalProperties": false } } } }, "410": { "description": "HTTP 410", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "upload_expired", "upload_cancelled" ] } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "HTTP 413", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "upload_too_large" ] } }, "required": [ "error" ] } } } }, "500": { "description": "HTTP 500", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "internal_error" ] } }, "required": [ "error" ] } } } }, "503": { "description": "HTTP 503", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "preparation_unavailable" ] } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/api/projects/{projectId}/uploads/{sessionId}/archive": { "put": { "operationId": "uploadArchive", "summary": "Upload a ZIP archive", "tags": [ "Uploads" ], "description": "Send the declared ZIP bytes as application/octet-stream using the upload authorization header. Preparation validates the archive before the version can be published.\n\nAccess: uploader\n\nMaximum request body: 52428800 bytes.", "security": [ { "uploadBearer": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{21}[AQgw]$" }, "required": true, "name": "projectId", "in": "path" }, { "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{21}[AQgw]$" }, "required": true, "name": "sessionId", "in": "path" } ], "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "responses": { "200": { "description": "HTTP 200", "content": { "application/json": { "schema": { "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 } } } }, "400": { "description": "HTTP 400", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "invalid_request" ] } }, "required": [ "error" ] } } } }, "401": { "description": "HTTP 401", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "unauthenticated" ] } }, "required": [ "error" ] } } } }, "403": { "description": "HTTP 403", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "insufficient_scope" ] } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "HTTP 404", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "project_not_found", "upload_not_found", "version_unavailable" ] } }, "required": [ "error" ], "additionalProperties": false } } } }, "410": { "description": "HTTP 410", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "upload_expired", "upload_cancelled" ] } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "HTTP 413", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "upload_too_large" ] } }, "required": [ "error" ] } } } }, "500": { "description": "HTTP 500", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "internal_error" ] } }, "required": [ "error" ] } } } }, "503": { "description": "HTTP 503", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "preparation_unavailable" ] } }, "required": [ "error" ], "additionalProperties": false } } } } } } } } }