--- title: Add a tab to an in-house Space document, optionally with Markdown and blocks as in createSpaceDocument description: The tab lands last. `name` holds at most 255 characters and no "/". `markdown` and `blocks` follow createSpaceDocument (`` tokens). canonical_url: https://orchestor.io/docs/en/space/rest-api/endpoint-reference/documents/post-create-space-document-tab markdown_url: https://orchestor.io/docs/en/space/rest-api/endpoint-reference/documents/post-create-space-document-tab.md --- # Add a tab to an in-house Space document, optionally with Markdown and blocks as in createSpaceDocument The tab lands last. `name` holds at most 255 characters and no "/". `markdown` and `blocks` follow createSpaceDocument (`` tokens). ```http POST /v1/space/documents/{document_id}/tabs ``` Server: https://api.orchestor.io Operation ID: `createSpaceDocumentTab` ## Authentication ```json [ [ { "key": "session_cookie", "type": "apiKey", "description": "Browser session established by signing in to the web app. The server checks your workspace membership and permissions. Supply X-Workspace-ID for workspace-scoped operations. For server-to-server requests, use an API key when the operation supports it.", "name": "wos-session", "in": "cookie", "scopes": [] } ], [ { "key": "bearer_api_key", "type": "http", "description": "Authenticate with a workspace-scoped API key using Authorization: Bearer . Supported key prefixes are sk_live_ and sk_test_. The key determines the workspace and allowed permissions; supplying X-Workspace-ID does not grant access to another workspace. Create and manage API keys in workspace settings. Never put a key in a URL.", "scheme": "bearer", "scopes": [] } ] ] ``` ## Parameters ```json [ { "name": "X-Workspace-ID", "in": "header", "required": false, "description": "Workspace to access. With a workspace-scoped API key, the server derives this value from the key, so the header is optional. If supplied, it must match the credential workspace or the request returns 403 workspace_mismatch. For interactive session requests, supply this header to select a workspace where you are a member. A project ID cannot be used as a workspace ID.", "schema": { "type": "string", "example": "wks_abc123" } }, { "name": "document_id", "in": "path", "required": true, "schema": { "pattern": "^doc_[a-f0-9]{24}$", "type": "string" } } ] ``` ## Request body ```json { "required": true, "content": [ { "contentType": "application/json", "schema": { "name": "CreateSpaceDocumentTab", "type": "object", "required": [ "name" ], "properties": { "blocks": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "object", "required": [ "type", "intent" ], "properties": { "intent": { "maxLength": 2000, "type": "string" }, "type": { "type": "string", "enumValues": [ "pending" ] } } }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enumValues": [ "paragraph" ] } } }, { "type": "object", "required": [ "type", "spec", "rows" ], "properties": { "caption": { "type": "string" }, "rows": { "maxItems": 2000, "type": "array", "description": "The rows the chart draws, as measured (≤ 2000 rows, 256 KiB).", "items": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] } } }, "spec": { "type": "object", "required": [ "kind", "title", "x", "y" ], "properties": { "kind": { "type": "string", "enumValues": [ "line", "bar", "pie" ] }, "series": { "type": "string", "description": "A column whose VALUES name the series: one row per series and period." }, "title": { "minLength": 1, "type": "string", "description": "The finding, with its number, not the topic." }, "unit": { "type": "string" }, "x": { "minLength": 1, "type": "string", "description": "The column along the axis (or the pie slices)." }, "y": { "minLength": 1, "type": "string", "description": "The measured column (numbers)." } } }, "type": { "type": "string", "enumValues": [ "chart" ] } } }, { "type": "object", "required": [ "type", "spec" ], "properties": { "caption": { "type": "string" }, "spec": { "type": "object", "required": [ "title", "direction", "nodes", "edges" ], "properties": { "direction": { "type": "string", "enumValues": [ "right", "down" ] }, "edges": { "maxItems": 120, "type": "array", "items": { "type": "object", "required": [ "from", "to" ], "properties": { "from": { "type": "string" }, "label": { "type": "string" }, "to": { "type": "string" } } } }, "nodes": { "minItems": 1, "maxItems": 60, "type": "array", "items": { "type": "object", "required": [ "id", "label" ], "properties": { "detail": { "type": "string" }, "id": { "pattern": "^[\\w-]{1,64}$", "type": "string" }, "label": { "minLength": 1, "type": "string" } } } }, "title": { "minLength": 1, "type": "string" } } }, "type": { "type": "string", "enumValues": [ "diagram" ] } } }, { "type": "object", "required": [ "type", "user" ], "properties": { "type": { "type": "string", "enumValues": [ "mention" ] }, "user": { "minLength": 1, "maxLength": 320, "type": "string" } } }, { "type": "object", "required": [ "type", "ref" ], "properties": { "ref": { "pattern": "^project\\/doc_[a-f0-9]{24}$", "type": "string" }, "type": { "type": "string", "enumValues": [ "mention" ] } } }, { "type": "object", "required": [ "type", "value" ], "properties": { "type": { "type": "string", "enumValues": [ "date" ] }, "value": { "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" } } } ] } }, "markdown": { "maxLength": 1000000, "type": "string", "description": "Markdown body. CLI: UTF-8 file path or - for stdin.", "default": "" }, "name": { "minLength": 1, "maxLength": 255, "type": "string" } }, "additionalProperties": false } } ] } ``` ## Responses ### 201 ```json { "statusCode": "201", "description": "Created tab", "headers": [], "content": [ { "contentType": "application/json", "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "name": "SpaceDocumentTab", "type": "object", "required": [ "id", "document_id", "name", "position", "updated_at" ], "properties": { "document_id": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "position": { "type": "integer" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } ] } ``` ### 400 ```json { "statusCode": "400", "description": "Invalid request parameters or body. Not retryable — fix the request before retrying.\nCommon error codes: `invalid_parameter` (wrong type or out of range),\n`missing_required_field` (a required body field is absent),\n`invalid_json` (request body is not valid JSON),\n`validation_error` (field fails schema validation, e.g., URL format or enum value).\n", "headers": [], "content": [ { "contentType": "application/json", "schema": { "name": "ApiError", "type": "object", "description": "Common structured error envelope. Use the HTTP status and error code to handle failures. Some endpoints declare more specific error schemas with additional fields.", "required": [ "error" ], "properties": { "error": { "type": "object", "description": "Failure category, code and human-readable explanation, with optional field or validation context.", "required": [ "type", "code", "message", "doc_url" ], "properties": { "type": { "type": "string", "description": "Broad error category for classifying the failure. The more specific code and HTTP status determine how to handle it.", "enumValues": [ "invalid_request_error", "authentication_error", "permission_error", "entitlement_error", "not_found_error", "rate_limit_error", "api_error" ] }, "code": { "type": "string", "description": "Machine-readable failure code. Preserve its case when matching it; handlers may return uppercase codes such as VALIDATION_ERROR or lowercase codes such as invalid_parameter. New codes may be added; supported codes depend on the endpoint.", "example": "VALIDATION_ERROR" }, "message": { "type": "string", "description": "Human-readable explanation of this failure. Wording can vary; use code rather than parsing this text for programmatic decisions.", "example": "Request validation failed" }, "feature": { "type": "string", "description": "Entitlement capability required for a 402 denial.", "example": "included_engines" }, "upgrade_url": { "type": "string", "format": "uri", "description": "Plan or grant recovery destination supplied with a 402 denial." }, "param": { "type": "string", "description": "Input field or parameter associated with the error, when supplied by the handler. Omitted when no single parameter is identified; validation failures may instead provide several entries in details.", "example": "limit" }, "doc_url": { "type": "string", "format": "uri", "description": "Documentation URL supplied with the error. Use the returned URL instead of constructing it from code; URL formatting can differ between handlers.", "example": "https://docs.orchestor.io/errors/validation_error" }, "details": { "description": "Additional failure context when supplied. Validation middleware returns an array of field issues; typed business errors return a code-specific object. Omission means no additional context was attached.", "anyOf": [ { "type": "array", "description": "Validation issues. A request can have multiple issues, including more than one for the same field.", "example": [ { "path": "items.0.name", "message": "Invalid input", "code": "invalid_type" } ], "items": { "type": "object", "required": [ "path", "message", "code" ], "properties": { "path": { "type": "string", "description": "Dot-separated path to the invalid value, including array indexes. An empty string identifies the root input.", "example": "items.0.name" }, "message": { "type": "string", "description": "Human-readable explanation of this validation issue. Use code and path for programmatic handling.", "example": "Invalid input" }, "code": { "type": "string", "description": "Validation issue code, such as invalid_type, or a custom code provided by the validator. It is distinct from the outer error.code.", "example": "invalid_type" } } } }, { "type": "object", "description": "Additional fields specific to the error code. Consult the endpoint's error documentation before interpreting them.", "additionalProperties": true } ] } } } } }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "limit must be between 1 and 200", "param": "limit", "doc_url": "https://docs.orchestor.io/api-reference/errors#invalid-request" } } } ] } ``` ### 401 ```json { "statusCode": "401", "description": "Authentication required or credentials invalid. Not retryable without new credentials.\nCommon error codes: `invalid_api_key` (key is missing, malformed, or revoked),\n`expired_session` (session cookie expired — re-authenticate via the web app).\n", "headers": [], "content": [ { "contentType": "application/json", "schema": { "name": "ApiError", "type": "object", "description": "Common structured error envelope. Use the HTTP status and error code to handle failures. Some endpoints declare more specific error schemas with additional fields.", "required": [ "error" ], "properties": { "error": { "type": "object", "description": "Failure category, code and human-readable explanation, with optional field or validation context.", "required": [ "type", "code", "message", "doc_url" ], "properties": { "type": { "type": "string", "description": "Broad error category for classifying the failure. The more specific code and HTTP status determine how to handle it.", "enumValues": [ "invalid_request_error", "authentication_error", "permission_error", "entitlement_error", "not_found_error", "rate_limit_error", "api_error" ] }, "code": { "type": "string", "description": "Machine-readable failure code. Preserve its case when matching it; handlers may return uppercase codes such as VALIDATION_ERROR or lowercase codes such as invalid_parameter. New codes may be added; supported codes depend on the endpoint.", "example": "VALIDATION_ERROR" }, "message": { "type": "string", "description": "Human-readable explanation of this failure. Wording can vary; use code rather than parsing this text for programmatic decisions.", "example": "Request validation failed" }, "feature": { "type": "string", "description": "Entitlement capability required for a 402 denial.", "example": "included_engines" }, "upgrade_url": { "type": "string", "format": "uri", "description": "Plan or grant recovery destination supplied with a 402 denial." }, "param": { "type": "string", "description": "Input field or parameter associated with the error, when supplied by the handler. Omitted when no single parameter is identified; validation failures may instead provide several entries in details.", "example": "limit" }, "doc_url": { "type": "string", "format": "uri", "description": "Documentation URL supplied with the error. Use the returned URL instead of constructing it from code; URL formatting can differ between handlers.", "example": "https://docs.orchestor.io/errors/validation_error" }, "details": { "description": "Additional failure context when supplied. Validation middleware returns an array of field issues; typed business errors return a code-specific object. Omission means no additional context was attached.", "anyOf": [ { "type": "array", "description": "Validation issues. A request can have multiple issues, including more than one for the same field.", "example": [ { "path": "items.0.name", "message": "Invalid input", "code": "invalid_type" } ], "items": { "type": "object", "required": [ "path", "message", "code" ], "properties": { "path": { "type": "string", "description": "Dot-separated path to the invalid value, including array indexes. An empty string identifies the root input.", "example": "items.0.name" }, "message": { "type": "string", "description": "Human-readable explanation of this validation issue. Use code and path for programmatic handling.", "example": "Invalid input" }, "code": { "type": "string", "description": "Validation issue code, such as invalid_type, or a custom code provided by the validator. It is distinct from the outer error.code.", "example": "invalid_type" } } } }, { "type": "object", "description": "Additional fields specific to the error code. Consult the endpoint's error documentation before interpreting them.", "additionalProperties": true } ] } } } } }, "example": { "error": { "type": "authentication_error", "code": "invalid_api_key", "message": "Invalid API key provided", "doc_url": "https://docs.orchestor.io/api-reference/errors#authentication" } } } ] } ``` ### 404 ```json { "statusCode": "404", "description": "The requested resource is unavailable in the current workspace or route scope. Check the identifier and selected workspace. The same response can be returned for a deleted resource or a resource outside your access scope.", "headers": [], "content": [ { "contentType": "application/json", "schema": { "name": "ApiError", "type": "object", "description": "Common structured error envelope. Use the HTTP status and error code to handle failures. Some endpoints declare more specific error schemas with additional fields.", "required": [ "error" ], "properties": { "error": { "type": "object", "description": "Failure category, code and human-readable explanation, with optional field or validation context.", "required": [ "type", "code", "message", "doc_url" ], "properties": { "type": { "type": "string", "description": "Broad error category for classifying the failure. The more specific code and HTTP status determine how to handle it.", "enumValues": [ "invalid_request_error", "authentication_error", "permission_error", "entitlement_error", "not_found_error", "rate_limit_error", "api_error" ] }, "code": { "type": "string", "description": "Machine-readable failure code. Preserve its case when matching it; handlers may return uppercase codes such as VALIDATION_ERROR or lowercase codes such as invalid_parameter. New codes may be added; supported codes depend on the endpoint.", "example": "VALIDATION_ERROR" }, "message": { "type": "string", "description": "Human-readable explanation of this failure. Wording can vary; use code rather than parsing this text for programmatic decisions.", "example": "Request validation failed" }, "feature": { "type": "string", "description": "Entitlement capability required for a 402 denial.", "example": "included_engines" }, "upgrade_url": { "type": "string", "format": "uri", "description": "Plan or grant recovery destination supplied with a 402 denial." }, "param": { "type": "string", "description": "Input field or parameter associated with the error, when supplied by the handler. Omitted when no single parameter is identified; validation failures may instead provide several entries in details.", "example": "limit" }, "doc_url": { "type": "string", "format": "uri", "description": "Documentation URL supplied with the error. Use the returned URL instead of constructing it from code; URL formatting can differ between handlers.", "example": "https://docs.orchestor.io/errors/validation_error" }, "details": { "description": "Additional failure context when supplied. Validation middleware returns an array of field issues; typed business errors return a code-specific object. Omission means no additional context was attached.", "anyOf": [ { "type": "array", "description": "Validation issues. A request can have multiple issues, including more than one for the same field.", "example": [ { "path": "items.0.name", "message": "Invalid input", "code": "invalid_type" } ], "items": { "type": "object", "required": [ "path", "message", "code" ], "properties": { "path": { "type": "string", "description": "Dot-separated path to the invalid value, including array indexes. An empty string identifies the root input.", "example": "items.0.name" }, "message": { "type": "string", "description": "Human-readable explanation of this validation issue. Use code and path for programmatic handling.", "example": "Invalid input" }, "code": { "type": "string", "description": "Validation issue code, such as invalid_type, or a custom code provided by the validator. It is distinct from the outer error.code.", "example": "invalid_type" } } } }, { "type": "object", "description": "Additional fields specific to the error code. Consult the endpoint's error documentation before interpreting them.", "additionalProperties": true } ] } } } } }, "example": { "error": { "type": "not_found_error", "code": "resource_not_found", "message": "Resource not found", "doc_url": "https://docs.orchestor.io/api-reference/errors#not-found" } } } ] } ``` --- [Documentation index](https://orchestor.io/docs/llms.txt)