--- title: HTTP API description: Look up HTTP API headers, routes, status codes, and errors. sidebar: order: 1 --- The Siglata HTTP API exposes core workspace services, authentication flows, and data transfer pipelines. The API provides typed error handling, strict multi-tenant boundaries, and internationalization. The default production base URL is: ```text https://www.siglata.com ``` ## Standard Headers [#standard-headers] All requests to the Siglata API utilize standard HTTP headers: | Header | Description | Example | | :-- | :-- | :-- | | `Authorization` | Bearer token for authenticated API and MCP transfer requests. | `Bearer sig_acc_9f8a7...` | | `x-siglata-locale` | Preferred language for transactional emails, invitation templates, and localized error messages. | `en-US` or `pt-BR` | | `Content-Type` | Payload format. Defaults to `application/json` for control endpoints and `application/octet-stream` for binary file chunks. | `application/json` | | `Origin` | Validated on MCP and CORS endpoints to prevent cross-origin abuse. | `https://example.com` | ## Core Service API [#core-api] ### Service Health & Session Check Inspect API availability, active localization, and current session identity. ```http GET /api HTTP/1.1 Host: www.siglata.com Authorization: Bearer x-siglata-locale: en-US ``` #### Response (`200 OK`) ```json { "service": "siglata", "status": "ok", "locale": "en-US", "user": { "id": "usr_9f8a7b6c5d", "email": "alex@example.com", "name": "Alex Smith", "image": null } } ``` When called without an active session or token, `user` returns `null`. ## Authentication Endpoints (`/auth/*`) [#auth-endpoints] Authentication endpoints manage passwordless credentials, sessions, and multi-tenant organizations. ### Request Magic Link Sends a one-time sign-in link to the user's email address in their requested language. ```http POST /auth/sign-in/magic-link HTTP/1.1 Host: www.siglata.com Content-Type: application/json x-siglata-locale: en-US { "email": "alex@example.com" } ``` #### Response (`200 OK`) ```json { "status": true } ``` ### Verify Magic Link Verifies a one-time magic link token and sets a secure, HTTP-only session cookie. ```http GET /auth/magic-link/verify?token=tok_3b4c5d6e7f HTTP/1.1 Host: www.siglata.com ``` ### Get Active Session Retrieves the currently authenticated session and user record. ```http GET /auth/get-session HTTP/1.1 Host: www.siglata.com ``` ### Sign Out Invalidates the active session and clears authentication cookies. ```http POST /auth/sign-out HTTP/1.1 Host: www.siglata.com ``` ### Organization Management Manage multi-tenant workspace boundaries and roles: #### Create Organization `POST /auth/organization/create` - **Body**: `{ "name": "Acme Corp", "slug": "acme-corp" }` - **Response**: Created organization record with ID. #### List User Organizations `GET /auth/organization/list` - **Response**: Array of organizations the user belongs to, including roles. #### Get Organization Details `GET /auth/organization/get?organizationId=org_1a2b3c4d5e` - **Response**: Detailed organization profile, members, and metadata. #### Invite Team Member `POST /auth/organization/invite-member` - **Headers**: `x-siglata-locale: en-US` (or `pt-BR`) - **Body**: `{ "email": "dev@example.com", "role": "member", "organizationId": "org_1a2b3c4d5e" }` - **Response**: Created invitation record. #### List Pending Invitations `GET /auth/organization/list-invitations?organizationId=org_1a2b3c4d5e` - **Response**: Array of pending invitations. #### Cancel Invitation `POST /auth/organization/cancel-invitation` - **Body**: `{ "invitationId": "inv_9a8b7c6d5e" }` #### Update Member Role `POST /auth/organization/update-member-role` - **Body**: `{ "memberId": "usr_3c4d5e6f7g", "role": "admin", "organizationId": "org_1a2b3c4d5e" }` #### Remove Member `POST /auth/organization/remove-member` - **Body**: `{ "memberIdOrEmail": "usr_3c4d5e6f7g", "organizationId": "org_1a2b3c4d5e" }` ### OAuth 2.0 Discovery Endpoints Siglata publishes standard discovery documents for OAuth 2.0 and MCP clients: - `GET /.well-known/oauth-authorization-server` - `GET /.well-known/openid-configuration` - `GET /.well-known/oauth-protected-resource/v1/mcp` ## Model Context Protocol & Transfer Endpoints (`/v1/mcp/*`) [#mcp-endpoints] The `/v1/mcp/*` endpoints handle JSON-RPC protocol messages and high-throughput binary file transfers. `tools/list` exposes only two tools, `execute` and `search`, and management operations run inside `execute` scripts. ### JSON-RPC Streamable HTTP ```http POST /v1/mcp HTTP/1.1 Host: www.siglata.com Authorization: Bearer Content-Type: application/json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "execute", "arguments": { "script": "return await files_list({ state: 'active', limit: 25 });" } } } ``` ### Upload Binary Chunk Transfers a single 8 MiB part for an active upload reservation created via `upload_begin`. ```http PUT /v1/mcp/uploads/{uploadId}/parts/{partNumber} HTTP/1.1 Host: www.siglata.com Authorization: Bearer Content-Type: application/octet-stream ``` - `partNumber`: 1-indexed integer (1 to 10,000). - Response: `200 OK` on successful chunk verification and storage. ### Authenticated Binary Download Streams stored file bytes directly to the authorized caller. ```http GET /v1/mcp/files/{fileId}/download HTTP/1.1 Host: www.siglata.com Authorization: Bearer ``` - **Response**: `200 OK` with `Content-Type` matching original media type, `Content-Length`, and `Content-Disposition: attachment`. - Verifies active organization membership before initiating the stream. ## HTTP Status Codes [#status-codes] | Status | Code | Meaning | | :-- | :-- | :-- | | `200` | OK | Request succeeded; response payload returned. | | `201` | Created | Resource created successfully (e.g. organization, invitation). | | `204` | No Content | Action completed successfully with no response body. | | `400` | Bad Request | Malformed payload, invalid schema, or part size mismatch. | | `401` | Unauthorized | Missing or invalid authentication token, or session expired. | | `403` | Forbidden | Insufficient OAuth scope, membership required, or origin disallowed. | | `404` | Not Found | Target file, upload, organization, or invitation does not exist. | | `409` | Conflict | Storage quota exceeded, or concurrent state collision. | | `410` | Gone | Upload reservation has expired or 30-day trash recovery window lapsed. | | `500` | Internal Error | Server-side execution exception. | ## Error Taxonomy [#error-taxonomy] Siglata returns structured, typed errors with predictable machine-readable codes: ```json { "code": "quota_exceeded", "message": "Storage quota limit reached for this organization" } ``` ### Common Error Codes | Error Code | HTTP Status | Description | | :-- | :-- | :-- | | `invalid_input` | 400 | One or more parameters failed validation rules. | | `part_mismatch` | 400 | Chunk size does not match expected 8 MiB size. | | `upload_incomplete` | 400 | Attempted to complete upload with missing parts. | | `SESSION_EXPIRED` | 401 | Authorizing session has lapsed; re-authentication required. | | `INSUFFICIENT_SCOPE` | 403 | OAuth grant lacks the scope required for this operation, or the org's MCP `maxScopes` ceiling excludes it. | | `MCP_ACCESS_REVOKED` | 403 | Organization MCP access is `revoked`. Missing rows auto-ensure `testing`. | | `ORGANIZATION_MEMBERSHIP_REQUIRED` | 403 | User is not an active member of the requested organization. | | `ORGANIZATION_ADMIN_REQUIRED` | 403 | Operation requires `owner` or `admin` organizational privileges. | | `ORIGIN_NOT_ALLOWED` | 403 | Request origin rejected by CORS security policy. | | `not_found` | 404 | File, upload, or organization record not found. | | `INVITATION_NOT_FOUND` | 404 | Targeted invitation ID does not exist. | | `quota_exceeded` | 409 | Upload cannot proceed because it exceeds the 10 GiB limit. | | `conflict` | 409 | Concurrent modification or state conflict. | | `upload_expired` | 410 | Upload reservation expired before completion. | | `restore_expired` | 410 | File has passed the 30-day trash recovery window. | | `storage_failure` | 500 | Storage backend operation encountered an unexpected error. | | `database_failure` | 500 | Database query or transaction failure. |