{ "openapi": "3.1.0", "info": { "title": "SynckHub Repository Integration API", "version": "1.0.0", "description": "Stable machine-to-machine read API for repository inventory, filtered search, permissions, file bytes, and file history. Exchange a repo API token with SynckHub Common for a short-lived access token, then send that access token as a bearer token to these endpoints.\n\n## Authentication and routing\nCreate a repository token in Settings → API tokens. At your deployment’s Common base URL, call POST /v1/api-tokens/exchange with `Authorization: Bearer `. Use access_token as the bearer credential and api_base_url as the server URL below. The opaque repository token is not accepted by these endpoints. Exchange again before access_token_expires_at or after a routing failure. The machine principal has the ADMIN role in exactly one repository.\n\n## Scope\nThis is the supported repository read profile, not the entire platform API. Writes, uploads, webhooks, and incremental synchronization are outside this contract. Unfiltered listing and search exclude DATABASE, TABLE, and FILE_VERSION_SET; request those item types explicitly when needed. A paged inventory is not an atomic snapshot or a complete repository backup.\n\n[Integration guide](https://synckhub.com/documentation/developers/api/repository-integration-api) · [Other API families](https://synckhub.com/documentation/developers/api)" }, "servers": [ { "url": "{apiBaseUrl}", "variables": { "apiBaseUrl": { "default": "https://api.example.synckhub.com", "description": "The repository API base URL returned by Common API-token exchange." } } } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Discovery", "description": "Discover the machine-readable contract without authentication." }, { "name": "Items", "description": "Enumerate visible items, filter a subtree, and inspect item metadata." }, { "name": "Content", "description": "Read current file bytes, expiring download URLs, content revisions, and named versions." }, { "name": "Permissions", "description": "Inspect the machine principal’s effective access at repository, folder, or item scope." } ], "paths": { "/openapi/integration-v1.json": { "get": { "operationId": "getIntegrationOpenApi", "summary": "Get this OpenAPI document", "tags": [ "Discovery" ], "security": [], "responses": { "200": { "description": "OpenAPI 3.1 document", "content": { "application/vnd.oai.openapi+json;version=3.1": { "schema": { "type": "object" } } } } } } }, "/repos/{repo_id}/items": { "get": { "operationId": "listItems", "summary": "List repository items", "description": "Lists visible live items. Omit parent_folder_id to scan across repository folders. Without item_type, DATABASE, TABLE, and FILE_VERSION_SET are excluded; request those types explicitly to include them. For cursor paging, use sort=name, order=asc, and pass both next_cursor values as after_name and after_item_id. Do not combine a cursor with a nonzero offset. next_cursor is absent on the final cursor page. Pages are read independently, not as an atomic snapshot.", "tags": [ "Items" ], "parameters": [ { "$ref": "#/components/parameters/RepoId" }, { "name": "parent_folder_id", "in": "query", "description": "Parent folder ID. An empty value selects repository-root children; omit for all visible repository items.", "schema": { "type": "string" }, "example": "33333333-3333-4333-8333-333333333333" }, { "name": "item_type", "in": "query", "description": "Item-type filter. Explicit selection includes types otherwise hidden from inventory: DATABASE, TABLE, and FILE_VERSION_SET. Repeat this parameter for multiple types.", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true, "example": [ "FILE" ] }, { "name": "file_extension", "in": "query", "description": "Repeatable lowercase extension filter. Requires item_type=FILE.", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true }, { "name": "limit", "in": "query", "description": "Page size. Defaults to 1000.", "schema": { "type": "integer", "minimum": 1, "default": 1000 }, "example": 200 }, { "$ref": "#/components/parameters/Offset" }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "name", "date", "modified", "size", "extension" ], "default": "name" } }, { "name": "order", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" } }, { "name": "after_name", "in": "query", "schema": { "type": "string" }, "description": "Pass together with the other cursor field, sort=name, order=asc, and offset=0." }, { "name": "after_item_id", "in": "query", "schema": { "type": "string" }, "description": "Pass together with the other cursor field, sort=name, order=asc, and offset=0." } ], "responses": { "200": { "description": "List page with another cursor page available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemList" }, "example": { "items": [ { "repo_id": "11111111-1111-4111-8111-111111111111", "item_id": "22222222-2222-4222-8222-222222222222", "item_type": "FILE", "item_subtype": "STANDARD", "name": "report.pdf", "file_extension": "pdf", "parent_folder_id": "33333333-3333-4333-8333-333333333333", "path": "33333333-3333-4333-8333-333333333333.22222222-2222-4222-8222-222222222222", "lifecycle_state": "LIVE", "size": 2048, "head_revision_item_seq": 7, "last_updated_at": "2026-10-08T10:00:00Z", "last_updated_by": "service:api-token:44444444-4444-4444-8444-444444444444", "locks": [] } ], "next_cursor": { "after_name": "report.pdf", "after_item_id": "22222222-2222-4222-8222-222222222222" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" } } } }, "/repos/{repo_id}/items/search": { "get": { "operationId": "searchItems", "summary": "Search and filter repository items", "description": "The q parameter searches item names and is optional; omit it for a filtered inventory. Set parent_folder_id and recursive=true for a folder subtree. Without item_type, DATABASE, TABLE, and FILE_VERSION_SET are excluded. Search uses offset paging, not next_cursor: inspect page.has_next and advance offset by page.returned. Pages are read independently, not as an atomic snapshot. sort=location requires recursive=true.", "tags": [ "Items" ], "parameters": [ { "$ref": "#/components/parameters/RepoId" }, { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Item-name query, not file-body full-text search.", "example": "report" }, { "name": "parent_folder_id", "in": "query", "schema": { "type": "string" }, "example": "33333333-3333-4333-8333-333333333333" }, { "name": "recursive", "in": "query", "schema": { "type": "boolean", "default": false } }, { "name": "item_type", "in": "query", "schema": { "type": "string" }, "description": "Item-type filter. Explicit selection includes types otherwise hidden from inventory: DATABASE, TABLE, and FILE_VERSION_SET. Select one type.", "example": "FILE" }, { "name": "file_extension", "in": "query", "description": "Comma-separated lowercase file extensions.", "schema": { "type": "string" } }, { "name": "updated_by", "in": "query", "description": "Comma-separated actor IDs.", "schema": { "type": "string" } }, { "name": "updated_at_from", "in": "query", "schema": { "type": "string", "format": "date-time" }, "example": "2026-10-01T00:00:00Z" }, { "name": "updated_at_to", "in": "query", "schema": { "type": "string", "format": "date-time" }, "example": "2026-10-08T23:59:59Z" }, { "name": "limit", "in": "query", "description": "Page size. Values above 200 are capped at 200.", "schema": { "type": "integer", "minimum": 1, "default": 50, "maximum": 200 }, "example": 200 }, { "$ref": "#/components/parameters/Offset" }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "name", "date", "modified", "size", "extension", "location" ] } }, { "name": "order", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Final offset-paged search result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemList" }, "example": { "items": [ { "repo_id": "11111111-1111-4111-8111-111111111111", "item_id": "22222222-2222-4222-8222-222222222222", "item_type": "FILE", "item_subtype": "STANDARD", "name": "report.pdf", "file_extension": "pdf", "parent_folder_id": "33333333-3333-4333-8333-333333333333", "path": "33333333-3333-4333-8333-333333333333.22222222-2222-4222-8222-222222222222", "lifecycle_state": "LIVE", "size": 2048, "head_revision_item_seq": 7, "last_updated_at": "2026-10-08T10:00:00Z", "last_updated_by": "service:api-token:44444444-4444-4444-8444-444444444444", "locks": [] } ], "page": { "limit": 50, "offset": 0, "returned": 1, "has_prev": false, "has_next": false, "total_items": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" } } } }, "/repos/{repo_id}/items/{item_id}": { "get": { "operationId": "getItem", "summary": "Get item metadata", "tags": [ "Items" ], "parameters": [ { "$ref": "#/components/parameters/RepoId" }, { "$ref": "#/components/parameters/ItemId" } ], "responses": { "200": { "description": "Item metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Item" }, "example": { "repo_id": "11111111-1111-4111-8111-111111111111", "item_id": "22222222-2222-4222-8222-222222222222", "item_type": "FILE", "item_subtype": "STANDARD", "name": "report.pdf", "file_extension": "pdf", "parent_folder_id": "33333333-3333-4333-8333-333333333333", "path": "33333333-3333-4333-8333-333333333333.22222222-2222-4222-8222-222222222222", "lifecycle_state": "LIVE", "size": 2048, "head_revision_item_seq": 7, "last_updated_at": "2026-10-08T10:00:00Z", "last_updated_by": "service:api-token:44444444-4444-4444-8444-444444444444", "locks": [] } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } } }, "/repos/{repo_id}/items/{item_id}/content": { "get": { "operationId": "downloadItem", "summary": "Download current file bytes", "description": "Returns the stored file bytes, not derived text. Supports a single Range: bytes=… request when the blob store supports seeking. Federated blob reads may reject ranges with 501 RANGE_NOT_SUPPORTED.", "tags": [ "Content" ], "parameters": [ { "$ref": "#/components/parameters/RepoId" }, { "$ref": "#/components/parameters/ItemId" }, { "name": "Range", "in": "header", "description": "A single byte range for resumable downloads.", "schema": { "type": "string" }, "example": "bytes=0-1023" } ], "responses": { "200": { "description": "Raw file bytes", "headers": { "Content-Length": { "schema": { "type": "integer" } }, "ETag": { "description": "Quoted blob identity.", "schema": { "type": "string" } }, "Accept-Ranges": { "description": "bytes when seeking is supported; otherwise none.", "schema": { "type": "string" } } }, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "206": { "description": "Requested byte range", "headers": { "Content-Length": { "schema": { "type": "integer" } }, "ETag": { "description": "Quoted blob identity.", "schema": { "type": "string" } }, "Accept-Ranges": { "description": "bytes when seeking is supported; otherwise none.", "schema": { "type": "string" } }, "Content-Range": { "schema": { "type": "string" }, "example": "bytes 0-1023/2048" } }, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "416": { "description": "Invalid or unsatisfiable byte range.", "headers": { "Content-Range": { "schema": { "type": "string" }, "example": "bytes */2048" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "RANGE_NOT_SATISFIABLE", "message": "range not satisfiable" } } } }, "501": { "description": "Ranges are unsupported for this blob source.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "RANGE_NOT_SUPPORTED", "message": "range requests are not supported for federated blob reads" } } } } } } }, "/repos/{repo_id}/items/{item_id}/content-url": { "get": { "operationId": "getItemDownloadUrl", "summary": "Create a short-lived download URL", "tags": [ "Content" ], "parameters": [ { "$ref": "#/components/parameters/RepoId" }, { "$ref": "#/components/parameters/ItemId" } ], "responses": { "200": { "description": "Short-lived download URL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DownloadUrl" }, "example": { "url": "https://api.example.synckhub.com/v1/downloads/EXAMPLE_TOKEN", "path": "/v1/downloads/EXAMPLE_TOKEN", "expires_at": "2026-10-08T10:05:00Z", "download_name": "report.pdf", "blob_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "size_bytes": 2048 } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "description": "Returns an expiring download capability. Use the returned URL promptly; do not store it as a durable file address or log its token. expires_at is an RFC3339 timestamp." } }, "/repos/{repo_id}/items/{item_id}/content-revisions": { "get": { "operationId": "getItemVersions", "summary": "List file content revisions", "description": "Lists immutable content revisions. Named business labels are available from the file-versions endpoint.", "tags": [ "Content" ], "parameters": [ { "$ref": "#/components/parameters/RepoId" }, { "$ref": "#/components/parameters/ItemId" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Offset" } ], "responses": { "200": { "description": "Content revisions", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ContentRevision" } }, "example": [ { "repo_id": "11111111-1111-4111-8111-111111111111", "item_id": "22222222-2222-4222-8222-222222222222", "item_seq": 7, "commit_id": "55555555-5555-4555-8555-555555555555", "commit_event_idx": 0, "event_type": "FILE::SET_CONTENT", "file_name": "report.pdf", "revision_origin": "LOCAL", "updated_at": "2026-10-08T10:00:00Z", "updated_by": "service:api-token:44444444-4444-4444-8444-444444444444", "suppression_state": "AVAILABLE" } ] } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } } }, "/repos/{repo_id}/items/{item_id}/content-revisions/{item_seq}": { "get": { "operationId": "getVersion", "summary": "Get one file content revision", "description": "Returns revision metadata and blob_id. Download the revision bytes from the blob endpoint.", "tags": [ "Content" ], "parameters": [ { "$ref": "#/components/parameters/RepoId" }, { "$ref": "#/components/parameters/ItemId" }, { "$ref": "#/components/parameters/ItemSeq" } ], "responses": { "200": { "description": "Content revision", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentRevisionDetail" }, "example": { "repo_id": "11111111-1111-4111-8111-111111111111", "item_id": "22222222-2222-4222-8222-222222222222", "item_seq": 7, "blob_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "size": 2048, "commit_id": "55555555-5555-4555-8555-555555555555", "commit_event_idx": 0, "updated_at": "2026-10-08T10:00:00Z", "updated_by": "service:api-token:44444444-4444-4444-8444-444444444444", "suppression_state": "AVAILABLE" } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } } }, "/repos/{repo_id}/items/{item_id}/file-versions": { "get": { "operationId": "listNamedFileVersions", "summary": "List named file versions", "tags": [ "Content" ], "parameters": [ { "$ref": "#/components/parameters/RepoId" }, { "$ref": "#/components/parameters/ItemId" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Offset" } ], "responses": { "200": { "description": "Named file versions", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/NamedFileVersion" } }, "example": [ { "repo_id": "11111111-1111-4111-8111-111111111111", "item_id": "22222222-2222-4222-8222-222222222222", "version_id": "66666666-6666-4666-8666-666666666666", "lifecycle_state": "LIVE", "kind": "MAJOR", "label_source": "INTERNAL", "order_key": 1, "version_major": 1, "version_minor": 0, "description": "Approved report", "comment": null, "blob_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "size": 2048, "source_item_seq": 7, "last_commit_id": "55555555-5555-4555-8555-555555555555", "last_commit_event_idx": 0 } ] } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "description": "Lists named business labels, separate from immutable content revisions. Defaults to 100 labels per page; advance offset by the number returned and continue until an empty page." } }, "/repos/{repo_id}/blobs/{blob_id}": { "get": { "operationId": "downloadBlob", "summary": "Download bytes for a resolved content revision", "description": "Use blob IDs returned by version endpoints. Authorization is still evaluated in the repository context. Supports a single Range: bytes=… request when the blob store supports seeking. Federated blob reads may reject ranges with 501 RANGE_NOT_SUPPORTED.", "tags": [ "Content" ], "parameters": [ { "$ref": "#/components/parameters/RepoId" }, { "name": "blob_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Range", "in": "header", "description": "A single byte range for resumable downloads.", "schema": { "type": "string" }, "example": "bytes=0-1023" } ], "responses": { "200": { "description": "Raw blob bytes", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } }, "headers": { "ETag": { "description": "Quoted blob identity.", "schema": { "type": "string" } }, "Accept-Ranges": { "description": "bytes when seeking is supported; otherwise none.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "206": { "description": "Requested byte range", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } }, "headers": { "ETag": { "description": "Quoted blob identity.", "schema": { "type": "string" } }, "Accept-Ranges": { "description": "bytes when seeking is supported; otherwise none.", "schema": { "type": "string" } }, "Content-Range": { "schema": { "type": "string" }, "example": "bytes 0-1023/2048" } } }, "416": { "description": "Invalid or unsatisfiable byte range.", "headers": { "Content-Range": { "schema": { "type": "string" }, "example": "bytes */2048" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "RANGE_NOT_SATISFIABLE", "message": "range not satisfiable" } } } }, "501": { "description": "Ranges are unsupported for this blob source.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "RANGE_NOT_SUPPORTED", "message": "range requests are not supported for federated blob reads" } } } } } } }, "/repos/{repo_id}/authz/effective/self": { "get": { "operationId": "getItemPermissions", "summary": "Get the caller's effective permissions", "description": "Select at most one target. Omit all target parameters for repository permissions, pass folder_id for a folder, or item_id for an item.", "tags": [ "Permissions" ], "parameters": [ { "$ref": "#/components/parameters/RepoId" }, { "name": "folder_id", "in": "query", "schema": { "type": "string" } }, { "name": "item_id", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Effective permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EffectivePermissions" }, "example": { "principal_id": "service:api-token:44444444-4444-4444-8444-444444444444", "resource_kind": "ITEM", "resource_id": "22222222-2222-4222-8222-222222222222", "allowed_actions": [ "SEE_METADATA", "READ_CONTENT" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Short-lived access token returned by the Common API token exchange. Do not send the long-lived opaque repo API token to repository endpoints." } }, "parameters": { "RepoId": { "name": "repo_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "11111111-1111-4111-8111-111111111111" }, "ItemId": { "name": "item_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "22222222-2222-4222-8222-222222222222" }, "ItemSeq": { "name": "item_seq", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64", "minimum": 1 }, "example": 7 }, "Limit": { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 100 }, "description": "Page size for history lists. Defaults to 100. Use offset to continue." }, "Offset": { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } }, "responses": { "ItemList": { "description": "Item page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemList" } } } }, "Error": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "Error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "description": "Branch on HTTP status and code; message is human-readable context. A 403 is not an empty result. A 404 may hide an item’s existence." }, "Item": { "type": "object", "required": [ "repo_id", "item_id", "item_type", "name", "parent_folder_id", "path", "lifecycle_state" ], "properties": { "repo_id": { "type": "string" }, "item_id": { "type": "string" }, "item_type": { "type": "string", "description": "Platform item type, for example FILE, FOLDER, DATABASE, or TABLE." }, "item_subtype": { "type": "string" }, "name": { "type": "string" }, "file_extension": { "type": [ "string", "null" ] }, "parent_folder_id": { "type": [ "string", "null" ] }, "path": { "type": "string", "description": "Raw platform ltree path: ancestor folder identifiers followed by this item’s identifier." }, "lifecycle_state": { "type": "string", "enum": [ "LIVE", "TRASH", "TOMBSTONED" ] }, "size": { "type": [ "integer", "null" ], "format": "int64" }, "head_revision_item_seq": { "type": [ "integer", "null" ], "format": "int64" }, "metadata_json": true, "last_updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_updated_by": { "type": [ "string", "null" ] } }, "additionalProperties": true, "description": "Visible item metadata. path is a dot-separated chain of literal item identifiers, preserving hyphens, not a human-readable filesystem path. Additional response fields may be returned; clients must ignore unknown fields.", "example": { "repo_id": "11111111-1111-4111-8111-111111111111", "item_id": "22222222-2222-4222-8222-222222222222", "item_type": "FILE", "item_subtype": "STANDARD", "name": "report.pdf", "file_extension": "pdf", "parent_folder_id": "33333333-3333-4333-8333-333333333333", "path": "33333333-3333-4333-8333-333333333333.22222222-2222-4222-8222-222222222222", "lifecycle_state": "LIVE", "size": 2048, "head_revision_item_seq": 7, "last_updated_at": "2026-10-08T10:00:00Z", "last_updated_by": "service:api-token:44444444-4444-4444-8444-444444444444", "locks": [] } }, "ItemList": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Item" } }, "next_cursor": { "oneOf": [ { "$ref": "#/components/schemas/ListCursor" }, { "type": "null" } ], "description": "Cursor for the next name-ascending list page; absent on the final page and on offset-paged search results." }, "page": { "oneOf": [ { "$ref": "#/components/schemas/OffsetPage" }, { "type": "null" } ], "description": "Offset paging metadata. Advance offset by returned when has_next is true." } }, "additionalProperties": true }, "ListCursor": { "type": "object", "required": [ "after_name", "after_item_id" ], "properties": { "after_name": { "type": "string" }, "after_item_id": { "type": "string" } } }, "DownloadUrl": { "type": "object", "required": [ "url", "path", "expires_at", "download_name", "blob_id", "size_bytes" ], "properties": { "url": { "type": "string", "format": "uri" }, "path": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" }, "download_name": { "type": "string" }, "blob_id": { "type": [ "string", "null" ] }, "size_bytes": { "type": [ "integer", "null" ] } } }, "ContentRevision": { "type": "object", "required": [ "repo_id", "item_id", "item_seq", "commit_id", "event_type", "file_name", "revision_origin", "updated_at", "updated_by", "suppression_state" ], "properties": { "repo_id": { "type": "string" }, "item_id": { "type": "string" }, "item_seq": { "type": "integer", "format": "int64" }, "commit_id": { "type": "string" }, "event_type": { "type": "string" }, "file_name": { "type": "string" }, "revision_origin": { "type": "string", "enum": [ "LOCAL", "FEDERATED" ] }, "updated_at": { "type": "string", "format": "date-time" }, "updated_by": { "type": "string" }, "suppression_state": { "type": "string", "enum": [ "AVAILABLE", "SUPPRESSED" ] }, "commit_event_idx": { "type": "integer" } }, "additionalProperties": true, "description": "Immutable content history, separate from named business labels. SUPPRESSED content is subject to the server’s access policy." }, "ContentRevisionDetail": { "type": "object", "required": [ "repo_id", "item_id", "item_seq", "blob_id", "commit_id", "commit_event_idx", "updated_at", "updated_by", "suppression_state" ], "properties": { "repo_id": { "type": "string" }, "item_id": { "type": "string" }, "item_seq": { "type": "integer", "format": "int64" }, "blob_id": { "type": "string" }, "size": { "type": [ "integer", "null" ], "format": "int64" }, "commit_id": { "type": "string" }, "commit_event_idx": { "type": "integer" }, "updated_at": { "type": "string", "format": "date-time" }, "updated_by": { "type": "string" }, "suppression_state": { "type": "string", "enum": [ "AVAILABLE", "SUPPRESSED" ] } }, "additionalProperties": true }, "NamedFileVersion": { "type": "object", "required": [ "repo_id", "item_id", "version_id", "lifecycle_state", "kind", "label_source", "blob_id" ], "properties": { "repo_id": { "type": "string" }, "item_id": { "type": "string" }, "version_id": { "type": "string" }, "lifecycle_state": { "type": "string" }, "kind": { "type": "string" }, "label_source": { "type": "string", "enum": [ "INTERNAL", "EXTERNAL" ] }, "description": { "type": [ "string", "null" ] }, "comment": { "type": [ "string", "null" ] }, "blob_id": { "type": "string" }, "size": { "type": [ "integer", "null" ], "format": "int64" }, "source_item_seq": { "type": [ "integer", "null" ], "format": "int64" }, "order_key": { "type": "integer", "format": "int64" }, "version_major": { "type": [ "integer", "null" ] }, "version_minor": { "type": [ "integer", "null" ] }, "last_commit_id": { "type": "string" }, "last_commit_event_idx": { "type": "integer" } }, "additionalProperties": true, "description": "Named business label. version_id is its stable identity; source_item_seq refers to the FILE content revision. Named label identity is separate from content history." }, "EffectivePermissions": { "type": "object", "required": [ "principal_id", "resource_kind", "resource_id", "allowed_actions" ], "properties": { "principal_id": { "type": "string" }, "resource_kind": { "type": "string", "enum": [ "REPO", "FOLDER", "ITEM" ] }, "resource_id": { "type": "string" }, "allowed_actions": { "type": "array", "items": { "type": "string" } } } }, "OffsetPage": { "type": "object", "required": [ "limit", "offset", "returned", "has_prev", "has_next" ], "properties": { "limit": { "type": "integer", "minimum": 0 }, "offset": { "type": "integer", "minimum": 0 }, "returned": { "type": "integer", "minimum": 0 }, "has_prev": { "type": "boolean" }, "has_next": { "type": "boolean" }, "total_items": { "type": "integer", "minimum": 0 }, "estimated_total_items": { "type": "integer", "minimum": 0 } }, "additionalProperties": true } } }, "externalDocs": { "description": "API guide and supported API families", "url": "https://synckhub.com/documentation/developers/api" } }