Private API

Support reference for the organization-scoped private API under `/api/private`.

• Current auth is the organization private API key.
• The middleware accepts either `Authorization: Bearer <token>` or the raw key in the `api-key` header.
• Example:

```bash curl -H "Authorization: Bearer <TOKEN>" "https://api.alloy.cx/api/private/storage/" ```

When an organization's `status` is `inactive`, the private API blocks all mutating methods:

• `POST`, `PUT`, `PATCH`, and `DELETE` return `403` with `{ error: "Organization is inactive", code: "ORGANIZATION_INACTIVE" }`.
• Side-effecting `GET` endpoints (e.g. `GET /api/private/stargate/?system=...`) are also blocked.
• Read-only `GET` endpoints (storage listing, metadata, downloads) continue to work.

• `/api/private/storage`
• `/api/private/trigger`
• `/api/private/stargate`
• `/api/private/employee`

Base URL: `{api_url}/api/private/storage`

These routes expose full organization storage access.

Call these routes from a trusted external service or narrow gateway. Do not inject the private API key into a structured workflow's `Run Code` or tool parameters without user's approval.

• Successful storage mutations return `success: true` and usually a `data.path` field with the canonical relative path.
• Upload validation failures return `400`.
• Uploads above the configured `STORAGE_MAX_UPLOAD_SIZE_MB` limit (default `10 MB`) return `413`.
• Upload has no replace/skip flag. If the target file already exists, the server truncates and rewrites it, returns `200`, and emits `storage_file.updated`.
• Upload has no conflict status for existing files, no ETag / `If-Match` precondition, and no optimistic concurrency control. Clients should treat duplicate uploads as last-write-wins.
• `GET /storage/meta` prefers a cached document hash when one already exists in `organization_documents.file_hash`; otherwise it computes the hash from the current file contents on demand.
• `POST /storage/rename` and `POST /storage/move` return `409` on target-path conflicts.
• The current private storage API does not expose `copy`, `stats`, folder-sharing, or managed database routes. Authenticated organization database routes are instead under `/api/organizations/{organization_id}/storage/databases`; see `databases.md`.
• Private storage upload follows the same extension and content-validation registry as the organization Storage upload route. The backend checks detected content where required and assigns the canonical MIME for the accepted extension instead of trusting the supplied MIME. SQLite database extensions (`.sqlite`, `.db3`, `.db`, `.sqlite3`) require detected SQLite content; uploading a database file does not automatically create a managed database alias. See `storage.md` for the supported upload formats.

Base URL: `{api_url}/api/private/trigger`

• The public trigger route accepts `{api_url}/api/public/trigger/{publicApiKey}/{workflowId}`.
• The backend URL-encodes both dynamic path segments when generating those URLs.
• Newly generated organization `public_api_key` values are 32-character lowercase hex strings, which are safe to use as URL path segments.

• The private trigger authenticates the caller with the organization private API key.
• The public trigger uses the key in its URL to identify the organization. Do not treat the URL key as proof that a request came from an expected third-party provider.
• Neither trigger provides generic verification for vendor signatures, request timestamps, nonces, or replayed events.
• Public and private trigger routes accept the parsed request body without enforcing the workflow's declared payload schema.
• When a provider signs its webhooks, verify the raw request body, signature, and timestamp in an ingress service or gateway. Forward a normalized payload to Alloy only after verification succeeds.
• Include the provider's stable event ID in the forwarded payload. Use it as a deduplication or idempotency key before causing side effects.
• Reject events outside the provider's allowed timestamp window. Keep signing secrets in the gateway or approved secret configuration, not in workflow payloads or launcher instructions.
• Immediate public and private trigger calls process the workflow synchronously before responding. A debounced public trigger is the exception because it records the event for later execution.
• For webhook providers with short acknowledgement deadlines, validate and durably queue the event in a gateway. Return the provider's expected success response before a worker invokes Alloy.

• Returns `404` when the workflow does not exist in the authenticated organization.
• Returns `404` when the workflow exists but has no `flow` or no `starting_step_id`.
• On success returns:
• `success: true`
• `data.runId`
• `data.result`

Base URL: `{api_url}/api/private/employee`

These routes let a server-side integration connect a custom chat system to an Alloy AI teammate. For the full external developer guide, see `references/custom-channel-integration.md`.

• The `contact` object accepts optional `id`, `first_name`, `last_name`, `email`, and `phone` fields. Supplied fields update the contact channel profile when the saved chat is created or continued.
• `conversation` and `contact` remain all-or-nothing: sending only one returns `400`.
• `attachments` defaults to `[]` when omitted. Only image attachments are forwarded into workflow input data; all attachments stay on the saved message.
• `is_async` is optional and defaults to `false`. Set it to `true` when the integration should receive a run ID immediately and poll the private workflow-run endpoint instead of waiting for completion.
• Attachment items require `size` to be an integer of at least `1`. The server validates decoded base64 content size against the configured chat attachment limits (`CHAT_MAX_ATTACHMENTS`, `CHAT_MAX_ATTACHMENT_SIZE_MB`, `CHAT_MAX_TOTAL_ATTACHMENT_SIZE_MB`; defaults `10`, `10`, `30`).
• When attachments exceed those limits, `POST` returns `422` with error code `ATTACHMENT_LIMIT_EXCEEDED`, a `reason` of `MAX_ATTACHMENT_COUNT`, `MAX_ATTACHMENT_SIZE`, or `MAX_TOTAL_ATTACHMENT_SIZE`, the offending `files`, and the `limits` object.

• `POST /employee/{employee_id}/messages` returns `success: true`, `data.runId`, `data.message`, `data.messageId`, `data.assistantMessageId`, and `data.attachments`.
• With synchronous execution, `data.message` contains the immediate workflow result and `data.attachments` contains generated workflow output attachments. Each item is `{ name, mime_type, size, data }` with base64-encoded file content, including encrypted attachments.
• With `is_async: true`, `data.message` is `null` and `data.attachments` is `[]`; use `data.runId` with `GET /api/private/workflow/run/{run_id}` to retrieve status and the completed output.
• `data.messageId` is `null` for one-off requests where `conversation` and `contact` are omitted. A saved asynchronous chat still returns the persisted incoming message ID.
• `data.assistantMessageId` identifies the saved AI reply for a synchronous saved chat. It is `null` for asynchronous and one-off requests.
• `POST` returns `404` when the AI teammate does not exist in the authenticated organization.
• `POST` returns `422` when the AI teammate is not ready to process messages or when attachments exceed the configured chat attachment limits.
• `GET` returns message objects plus pagination metadata.
• `GET` returns `404` when no saved chat exists for the supplied `channel` and `conversation_id`.
• The feedback route verifies the message inside the requested AI teammate, channel conversation, contact, and participant scope. A missing or out-of-scope message returns `404` with `{ "error": "Message not found" }`.

Base URL: `{api_url}/api/private/workflow`

• A missing or cross-organization run returns `404` with `{ "error": "Workflow run not found" }`.
• Finished output attachments use the same `{ name, mime_type, size, data }` base64 shape as synchronous employee-message responses.

Base URL: `{api_url}/api/private/stargate`

Stargate lets a gateway process poll Alloy for work routed to a named internal system, execute it against that internal system, and report the result back to Alloy. For the architecture and setup model, see `stargate.md`.

The gateway executes polled tasks with JSON bodies by default. For non-`GET`/`HEAD` tasks whose `body` is exactly `{ "body_b64": "<base64>" }`, it validates and decodes the string and forwards the bytes to the internal system; supply the appropriate `Content-Type` in task headers. Other body shapes remain JSON, and invalid base64 fails without calling the internal system. See `stargate.md` for header precedence and binary-body behavior.

• The gateway uses the same `api-key` authentication as the rest of the private API.
• `system` is a routing key. A gateway should only receive tasks for the internal system name it passes in the poll request.
• Returned tasks include `stargate_task_id`, `organization_id`, `system`, `method`, `uri`, `body`, `response`, `status`, `created_at`, and `updated_at`.
• Task statuses currently move through `created`, `requested`, `responded`, `completed`, or `failed`.
• The `GET` route checks for new work every `5` seconds during the long-poll window.
• The `POST` route currently accepts JSON, plain text, raw bytes, or empty bodies and stores the payload as text.
• `POST /{task_id}` returns `404` when the task is missing.
• `POST /{task_id}` returns `400` when the task is not currently in `requested` status.