{ "openapi": "3.1.1", "info": { "title": "Tigby API", "description": "EU-hosted agent-identity service by neuraforce GmbH. Org is implicit in the auth context and never appears in a URL; errors are RFC 9457 problem details carrying a stable code, a doc_url and an agent_hint.", "version": "0.1.0" }, "servers": [ { "url": "http://api.tigby.eu/" } ], "paths": { "/api/healthz": { "get": { "tags": [ "Health" ], "summary": "Report API and dependency health", "description": "Probes every dependency and reports one component entry each. Answers 200 while the service can serve and 503 once an essential component is unhealthy, so a load balancer can read the status code alone.", "operationId": "GetHealth", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthReport" } } } }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthReport" } } } } } } }, "/api/handles/{handle}": { "get": { "tags": [ "Identities" ], "summary": "Check whether a Handle can be registered", "description": "The wizard's live check. Answers 200 either way; available is false with the code and detail that POST /api/identities would refuse with. Creates nothing and reserves nothing.", "operationId": "CheckHandle", "parameters": [ { "name": "handle", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HandleAvailabilityResponse" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "api_key": [ ] } ] } }, "/api/profiles/{handle}": { "get": { "tags": [ "A2A Card" ], "summary": "Read a public profile", "description": "Everything tigby.eu/@handle renders, and the A2A 1.0 card with it. Takes no credential, because the profile is public. An unknown Handle and a deleted Identity answer alike with 404: a deleted Identity does not leak that it existed. Rate-limited per client rather than per Org, because there is no Org in an unauthenticated read.", "operationId": "GetPublicProfile", "parameters": [ { "name": "handle", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileResponse" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/api/events": { "get": { "tags": [ "Events" ], "summary": "List the Org's Events", "description": "Newest first; filter with type (e.g. email.recipient_blocked) and handle. Paged with a keyset cursor: a page carries next_cursor whenever an older Event exists, and handing that back as cursor returns the page strictly older than the last row of this one – so every Event the Org has is reachable by paging backwards, and Events arriving while you page cannot push an older one out of reach. A cursor is opaque; pass it back unchanged. Events are also pushed: register a Webhook under /api/identities/{handle}/webhooks. Org-level Events (tunnel.transfer_blocked, identity.deleted, account.deletion_started and their kin) reach nobody by Webhook, so this list is their only delivery route.", "operationId": "ListEvents", "parameters": [ { "name": "type", "in": "query", "schema": { "type": "string" } }, { "name": "handle", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventListResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "api_key": [ ] } ] } }, "/api/events/{id}": { "get": { "tags": [ "Events" ], "summary": "One Event", "operationId": "GetEvent", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventView" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "api_key": [ ] } ] } }, "/api/events/{id}/replay": { "post": { "tags": [ "Events" ], "summary": "Replay an Event to a Webhook", "description": "Queues the Event for delivery to the named Webhook, whether or not it was ever delivered there, and whether or not the Webhook currently subscribes to its type. The Webhook must belong to the Identity the Event concerns. The envelope carries the same evt_ id – receivers deduplicate on it – under a fresh request id, timestamp and signature.", "operationId": "ReplayEvent", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplayRequest" } } }, "required": true }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplayResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "api_key": [ ] } ] } }, "/api/account/deletion": { "post": { "tags": [ "Account" ], "summary": "Delete the account", "description": "Art. 17, and the end of everything: every Identity is torn down – Mailbox, Tunnel, Connectors (revoked at the platform), Vault namespace, Webhooks, Events – and then the Org itself is deleted, its Vault data key with it. Irreversible, and confirmed by sending the account's own email address as confirm. Answers 202; from that moment every credential of this Org is refused, so this response is the last one it gets. Only the Handles stay reserved: a Handle is never reissued. Export first if you want the data – POST /api/exports.", "operationId": "DeleteAccount", "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DeleteAccountRequest" } ] } } } }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountDeletionView" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "api_key": [ ] } ] } }, "/api/hits": { "post": { "tags": [ "Analytics" ], "summary": "Count one page view", "description": "Adds one to the counter for (day, host, path, language). Takes no credential and stores nothing about the caller. Answers 204 whether the view was counted or dropped by the day's page ceiling: a beacon has nothing to do with the answer either way.", "operationId": "RecordPageView", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HitRequest" } } }, "required": true }, "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/api/contact": { "post": { "tags": [ "Contact" ], "summary": "Send a message through the contact form", "description": "The § 5 DDG contact channel behind tigby.eu/contact. Takes no credential, stores nothing, and delivers into the mailbox a person reads. Answers 202 once the message has been submitted for delivery.", "operationId": "SendContactMessage", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactRequest" } } }, "required": true }, "responses": { "202": { "description": "Accepted" }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/api/auth/magic-link": { "post": { "tags": [ "Auth" ], "summary": "Sign up or sign in by email", "description": "One request for both: creates the Org on first contact (the ToS/DPA checkbox is required then) and mails a one-time link either way. Answers 202 for new and returning Orgs alike. In the Development environment the body also carries the link. Where the deployment has closed signup, a first contact also needs invite_code; signing in to an Org that already exists never does.", "operationId": "RequestMagicLink", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MagicLinkRequest" } } }, "required": true }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MagicLinkResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/api/auth/magic-link/consume": { "post": { "tags": [ "Auth" ], "summary": "Turn a magic link into a session", "description": "Consumes the one-time token from the link, marks the email verified, and mints a server-side session. The session token is returned exactly once.", "operationId": "ConsumeMagicLink", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsumeMagicLinkRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsumeMagicLinkResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/api/auth/session": { "get": { "tags": [ "Auth" ], "summary": "The current session and its Org", "description": "Also carries where the Org stands against the Terms of Service in force: which version it accepted, when the console gate closes, and whether it is closed now (ADR 0031).", "operationId": "GetSession", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CurrentSessionResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "api_key": [ ] } ] }, "delete": { "tags": [ "Auth" ], "summary": "Log out", "description": "Revokes the session server-side; the token stops working immediately.", "operationId": "DeleteSession", "responses": { "204": { "description": "No Content" }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "api_key": [ ] } ] } }, "/api/auth/tos/acceptance": { "post": { "tags": [ "Auth" ], "summary": "Accept the Terms of Service in force", "description": "Records that the account holder agreed to the current version of the Terms including the DPA, and opens the console gate a version bump closed. The acceptance is appended to the Org's history; nothing earlier is overwritten. The body must name the version being accepted. A session only: accepting a contract is the account holder's act, and an Admin Key belongs to an agent, which is also why no API surface is gated by a version bump.", "operationId": "AcceptTos", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TosAcceptanceRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TosStatusView" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "api_key": [ ] } ] } }, "/api/auth/whoami": { "get": { "tags": [ "Auth" ], "summary": "Which Org this credential acts for", "description": "The one call that works with every credential: a session, an Admin Key or an Identity Key. Answers with the Org and with what the credential is, which is how the CLI shows who it is logged in as.", "operationId": "GetWhoami", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhoamiResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "api_key": [ ] } ] } }, "/api/auth/device": { "post": { "tags": [ "Auth" ], "summary": "Open a CLI login", "description": "The terminal's half of tigby login: answers with a short code for the human and a device code for the poll. Unauthenticated by construction – the pending authorization belongs to nobody until an account holder confirms the code in the console.", "operationId": "StartDeviceAuthorization", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartDeviceRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartDeviceResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/api/auth/device/token": { "post": { "tags": [ "Auth" ], "summary": "Collect the Admin Key of a confirmed login", "description": "Answers 200 with the key on the first poll after the confirmation, and a problem with code authorization_pending, slow_down, device_code_denied, device_code_expired, device_code_used or device_code_invalid until then. The key is in exactly one response.", "operationId": "PollDeviceAuthorization", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceTokenRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceTokenResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/api/auth/device/{userCode}": { "get": { "tags": [ "Auth" ], "summary": "What a login code is asking for", "description": "The console's read before it confirms: the name the key will carry, what asked, and how long the code is good for.", "operationId": "GetDeviceAuthorization", "parameters": [ { "name": "userCode", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceAuthorizationView" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "api_key": [ ] } ] } }, "/api/auth/device/{userCode}/approve": { "post": { "tags": [ "Auth" ], "summary": "Confirm a CLI login", "description": "Mints a named Admin Key for the Org and hands it to the waiting terminal. The key is listed and revoked like any other under GET /api/keys.", "operationId": "ApproveDeviceAuthorization", "parameters": [ { "name": "userCode", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "api_key": [ ] } ] } }, "/api/auth/device/{userCode}/deny": { "post": { "tags": [ "Auth" ], "summary": "Refuse a CLI login", "description": "The terminal learns it on its next poll and stops. Nothing is minted.", "operationId": "DenyDeviceAuthorization", "parameters": [ { "name": "userCode", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "api_key": [ ] } ] } }, "/api/keys": { "get": { "tags": [ "API keys" ], "summary": "List the Org's live API keys", "description": "Name, scope, display prefix, creation and last use of every key that is not revoked. Newest first.", "operationId": "ListApiKeys", "responses": { "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyListResponse" } } } } }, "security": [ { "api_key": [ ] } ] }, "post": { "tags": [ "API keys" ], "summary": "Create an Admin Key", "description": "Mints a named Admin Key (tigby_admin_…) with Org scope. The key is in the response exactly once; only its SHA-256 is stored. Identity Keys (tigby_id_…) are minted with an Identity, not here.", "operationId": "CreateApiKey", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiKeyRequest" } } }, "required": true }, "responses": { "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatedApiKeyResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "api_key": [ ] } ] } }, "/api/keys/{id}": { "get": { "tags": [ "API keys" ], "summary": "One API key", "description": "The key the create's Location points at, as the list shows it – never the key itself, which exists in the create response and nowhere else. A revoked key answers 404: the surface is the Org's live keys, and revoking one takes it off that surface for good.", "operationId": "GetApiKey", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyView" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "api_key": [ ] } ] }, "delete": { "tags": [ "API keys" ], "summary": "Revoke an API key", "description": "The key stops authenticating immediately. Revoking a key that is already revoked is a no-op.", "operationId": "RevokeApiKey", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "204": { "description": "No Content" }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "api_key": [ ] } ] } }, "/api/identities": { "get": { "tags": [ "Identities" ], "summary": "List the Org's Identities", "description": "Every Identity that is not deleted, oldest first, with its status. Saga detail is on the single Identity.", "operationId": "ListIdentities", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityListResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "api_key": [ ] } ] }, "post": { "tags": [ "Identities" ], "summary": "Create an Identity", "description": "Validates the Handle, reserves it, and starts the provisioning saga: Mailbox, Tunnel, A2A Card, then the first Identity Key. Answers 202 with the saga; poll GET /api/identities/{handle} until status is ready or failed. That read carries no secret: once it is ready, GET /api/identities/{handle}/identity-key hands the Identity Key and the Mailbox's IMAP credentials over, once. A Handle is never reissued and every Org has a lifetime quota of Identities, deleted ones included.", "operationId": "CreateIdentity", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateIdentityRequest" } } }, "required": true }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "api_key": [ ] } ] } }, "/api/identities/{handle}": { "get": { "tags": [ "Identities" ], "summary": "An Identity with its saga", "description": "The status resource: the Identity and its newest saga step by step. Poll it while a saga runs – it carries no credential in any state, so repeating it is free. The Identity Key and the Mailbox password are handed over by GET /api/identities/{handle}/identity-key instead. An Identity Key may read its own Identity; Org scope reads any of the Org's. The Org's first ready Identity also carries onboarding: how long it took from signup to ready.", "operationId": "GetIdentity", "parameters": [ { "name": "handle", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "api_key": [ ] } ] }, "delete": { "tags": [ "Identities" ], "summary": "Delete an Identity", "description": "Starts the teardown saga: every Identity Key is revoked first, then the parts go in reverse order. Everything the Identity owns goes with it – the Mailbox and every message in it, the Tunnel, the A2A Card, the Vault namespace, the Webhooks, the Allowed Recipients, the Events and the export archives that carry its mail – and each Connector's credential is revoked at the platform it belongs to. Answers 202 with the saga; the Identity disappears from list and get once the saga is done. The Handle is never reissued, so none of this can be undone by creating it again.", "operationId": "DeleteIdentity", "parameters": [ { "name": "handle", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityResponse" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "api_key": [ ] } ] } }, "/api/identities/{handle}/identity-key": { "get": { "tags": [ "Identities" ], "summary": "The show-once secrets, handed over", "description": "The first Identity Key (tigby_id_…) and the Mailbox's IMAP credentials, once the saga has minted them. The one route that hands them over, so that asking whether provisioning finished does not: reading here is deliberate, and reading the status resource is not. Returns them on every call until POST /api/identities/{handle}/identity-key/ack says they were received or the short window closes – a dropped response must not destroy a secret that cannot be re-minted – and answers 200 with both fields absent once neither is waiting. An Identity Key may read its own Identity; Org scope reads any of the Org's.", "operationId": "RevealIdentityKey", "parameters": [ { "name": "handle", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentitySecretsResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "api_key": [ ] } ] } }, "/api/identities/{handle}/identity-key/ack": { "post": { "tags": [ "Identities" ], "summary": "Confirm the show-once secrets were received", "description": "Forgets the first Identity Key and the Mailbox password, because the caller says it has them. Until this is called they are returned on every read of GET /api/identities/{handle}/identity-key – a dropped response must not destroy a secret that cannot be re-minted – and a short window forgets them anyway if nobody ever does. Answers 204 whether or not anything was still waiting.", "operationId": "AcknowledgeIdentityKey", "parameters": [ { "name": "handle", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "api_key": [ ] } ] } }, "/api/identities/{handle}/retry": { "post": { "tags": [ "Identities" ], "summary": "Retry a failed saga", "description": "Puts a failed provisioning or teardown saga back on the runner, from the step that failed.", "operationId": "RetryIdentitySaga", "parameters": [ { "name": "handle", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityResponse" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "api_key": [ ] } ] } }, "/api/identities/{handle}/card": { "get": { "tags": [ "A2A Card" ], "summary": "Read an Identity's A2A Card", "description": "The editable card and the A2A 1.0 document rendered from it, exactly as the public profile serves them. An Identity Key may read its own card; Org scope reads any of the Org's. An Identity whose card step has not run yet reads as the default card.", "operationId": "GetAgentCard", "parameters": [ { "name": "handle", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "api_key": [ ] } ] }, "patch": { "tags": [ "A2A Card" ], "summary": "Edit an Identity's A2A Card", "description": "A JSON Merge Patch (RFC 7396) over the card: a field you leave out stays as it is, an object merges into what is there, an array replaces it whole, and null clears an optional field. Setting provider.organization is what puts \"Operated by …\" on the public page. The edit is live on the profile page and in the card JSON at once.", "operationId": "UpdateAgentCard", "parameters": [ { "name": "handle", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/JsonObject" } ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "api_key": [ ] } ] } }, "/api/identities/{handle}/messages": { "get": { "tags": [ "Mailbox" ], "summary": "List the Mailbox", "description": "The Identity's messages, newest first, with sender, subject, preview, the subaddress tag (handle+tag@) the message came in on, and the origin verdict Stalwart recorded on delivery (DMARC, falling back to SPF on the return path). Page with limit and offset – the one list in this API that does, because the page comes from the mail server rather than from Tigby's database: the search runs over the whole Mailbox and the mail server answers with an offset and a total, and Tigby will not invent a keyset over rows it does not hold. Everything Tigby pages itself uses a cursor (GET /api/events). Narrow with query, which the mail server matches against sender, recipients, subject and the bodies across the whole Mailbox, not just the page – total then counts the matches. Reading here does not mark messages seen. An Identity Key reads its own Mailbox; Org scope reads any.", "operationId": "ListMessages", "parameters": [ { "name": "handle", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32" } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "format": "int32" } }, { "name": "query", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageListResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "api_key": [ ] } ] } }, "/api/identities/{handle}/messages/{id}": { "get": { "tags": [ "Mailbox" ], "summary": "Read a message", "description": "Headers, the decoded text and HTML bodies, attachment metadata, the subaddress tag and the origin verdict. Attachment bytes are not served yet.", "operationId": "GetMessage", "parameters": [ { "name": "handle", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageDetail" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "api_key": [ ] } ] } }, "/api/identities/{handle}/mailbox/password": { "post": { "tags": [ "Mailbox" ], "summary": "Set a new IMAP password", "description": "Replaces the Mailbox's IMAP password and returns the new one – the only response that ever carries it. The previous password stops working at once. For a password that was lost, or one that was never collected from GET /api/identities/{handle}/identity-key.", "operationId": "RotateMailboxPassword", "parameters": [ { "name": "handle", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MailboxPasswordResponse" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "api_key": [ ] } ] } }, "/api/allowed-recipients": { "get": { "tags": [ "Allowed recipients" ], "summary": "List the Org-level entries", "description": "The entries that allow sending for every Identity of the Org. Identity-level entries live under /api/identities/{handle}/allowed-recipients. An entry whose expiry has passed is still listed and carries expired: true; it allows nothing, and a send to it is refused like any other stranger's.", "operationId": "ListAllowedRecipients", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AllowedRecipientListResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "api_key": [ ] } ] }, "post": { "tags": [ "Allowed recipients" ], "summary": "Allow a recipient for every Identity", "description": "An exact address, or a whole domain as '@kunde.de'. Freemail and disposable domains are refused as domains – a single '@gmail.com' would void the rule. Adding an existing entry returns it unchanged. Admin Key or session only; an Identity Key can never edit the list.", "operationId": "AddAllowedRecipient", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddAllowedRecipientRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AllowedRecipientView" } } } }, "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AllowedRecipientView" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "api_key": [ ] } ] } }, "/api/allowed-recipients/{id}": { "get": { "tags": [ "Allowed recipients" ], "summary": "One entry", "description": "The entry the add's Location points at, of either level, by id. Carries expired: true once its expiry has passed.", "operationId": "GetAllowedRecipient", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AllowedRecipientView" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "api_key": [ ] } ] }, "delete": { "tags": [ "Allowed recipients" ], "summary": "Remove an entry", "description": "Removes an entry of either level by id. Sends to that recipient are refused again from the next message on.", "operationId": "DeleteAllowedRecipient", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No Content" }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "api_key": [ ] } ] } }, "/api/identities/{handle}/allowed-recipients": { "get": { "tags": [ "Allowed recipients" ], "summary": "List an Identity's entries", "description": "The entries scoped to this Identity, the automatic ones granted on verified inbound included. The Org-level entries apply on top. An entry whose expiry has passed is still listed and carries expired: true – it allows nothing. An Identity Key may read its own list – knowing who it may write to is how an agent avoids refusals – but only an Admin Key changes it.", "operationId": "ListIdentityAllowedRecipients", "parameters": [ { "name": "handle", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AllowedRecipientListResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "api_key": [ ] } ] }, "post": { "tags": [ "Allowed recipients" ], "summary": "Allow a recipient for one Identity", "description": "As the Org-level add, but the entry covers only this Identity. Admin Key or session only.", "operationId": "AddIdentityAllowedRecipient", "parameters": [ { "name": "handle", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddAllowedRecipientRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AllowedRecipientView" } } } }, "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AllowedRecipientView" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "api_key": [ ] } ] } }, "/api/identities/{handle}/messages/send": { "post": { "tags": [ "Outbound mail" ], "summary": "Send mail as the Identity", "description": "Builds the message and submits it through the same policy point that judges SMTP submissions: every recipient must be an Allowed Recipient of the Identity or the Org, and the Org's rolling send limit must have room. The Identity's mail must not be stopped: while it is, the send is refused with mail_paused. Outbound mail carries the AI-disclosure footer unless the Identity has disabled it. A refusal names the blocked addresses; approving them is POST /api/allowed-recipients – an Admin Key's job, not this key's.", "operationId": "SendMessage", "parameters": [ { "name": "handle", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendRequest" } } }, "required": true }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "502": { "description": "Bad Gateway", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "api_key": [ ] } ] } }, "/api/identities/{handle}/ai-disclosure": { "get": { "tags": [ "Outbound mail" ], "summary": "Read the AI-disclosure setting", "operationId": "GetAiDisclosure", "parameters": [ { "name": "handle", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisclosureResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "api_key": [ ] } ] }, "put": { "tags": [ "Outbound mail" ], "summary": "Switch the AI-disclosure footer", "description": "Outbound agent mail is marked as coming from an AI agent by default (EU AI Act, Art. 50). Disabling requires acknowledge_warning: true after showing the warning, and is recorded as an event either way. Admin Key or session only.", "operationId": "SetAiDisclosure", "parameters": [ { "name": "handle", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisclosureRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisclosureResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "api_key": [ ] } ] } }, "/api/identities/{handle}/mail": { "get": { "tags": [ "Outbound mail" ], "summary": "Whether the Identity's outbound mail is stopped", "description": "The per-Identity mail kill switch, as it stands. Inbound mail is never affected by it: a stopped Identity keeps receiving, so nothing addressed to it is lost.", "operationId": "GetMailStatus", "parameters": [ { "name": "handle", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MailStatusResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "api_key": [ ] } ] }, "patch": { "tags": [ "Outbound mail" ], "summary": "Stop or restart the Identity's outbound mail", "description": "The fast lever against a compromised or misbehaving Identity, and the one that closes both doors: while it is set, POST …/messages/send answers 403 mail_paused and an SMTP submission on port 587 is refused with 550 5.7.1 mail_paused, so revoking the Identity Key is not the only stop. The Mailbox, its password and the Handle are all kept, inbound keeps arriving, and the change is recorded as an identity.mail_paused or identity.mail_resumed Event. Admin Key or session only – an Identity Key cannot stop or start itself.", "operationId": "PauseMail", "parameters": [ { "name": "handle", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MailPauseRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MailStatusResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "api_key": [ ] } ] } }, "/api/identities/{handle}/webhooks": { "get": { "tags": [ "Webhooks" ], "summary": "List an Identity's Webhooks", "description": "The delivery targets registered for this Identity, oldest first. The signing secret is never in the list.", "operationId": "ListWebhooks", "parameters": [ { "name": "handle", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookListResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "api_key": [ ] } ] }, "post": { "tags": [ "Webhooks" ], "summary": "Register a Webhook", "description": "An HTTPS endpoint plus the event types to subscribe, each from the subscribable catalog: email.received, email.recipient_blocked, identity.card_updated, identity.ai_disclosure_enabled, identity.ai_disclosure_disabled, identity.mail_paused, identity.mail_resumed, tunnel.transfer_warning, tunnel.transfer_blocked, tunnel.stream_limit_reached, connector.connected, connector.disconnected, connector.mention, connector.reply, connector.dm, connector.post_blocked, connector.post_failed, connector.disclosure_missing, export.ready, export.failed. The two Org-level types (identity.deleted, account.deletion_started) belong to no Identity and are delivered to no Webhook; they are read from GET /api/events and a subscription naming one is refused with event_type_not_subscribable. Deliveries are signed with the Identity's signing secret (HMAC-SHA256 over '{request_id}.{timestamp}.{body}', X-Tigby-Request-Id / X-Tigby-Timestamp / X-Tigby-Signature); the first Webhook of an Identity mints that secret and this response is the only place it is ever shown. Failed deliveries retry after 30s, 5m, 30m, 2h, 6h and 24h – seven attempts in all – then the delivery is marked failed.", "operationId": "CreateWebhook", "parameters": [ { "name": "handle", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookView" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "api_key": [ ] } ] } }, "/api/identities/{handle}/webhooks/{id}": { "get": { "tags": [ "Webhooks" ], "summary": "One Webhook", "description": "The Webhook the create's Location points at. RFC 9110 makes Location on a 201 the identifier of the resource created, so it names this route and not the collection; the signing secret is never in it.", "operationId": "GetWebhook", "parameters": [ { "name": "handle", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookView" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "api_key": [ ] } ] }, "patch": { "tags": [ "Webhooks" ], "summary": "Change a Webhook", "description": "Changes the URL, the event types, or both; an absent field keeps its value. Pending deliveries go to the new URL.", "operationId": "UpdateWebhook", "parameters": [ { "name": "handle", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWebhookRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookView" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "api_key": [ ] } ] }, "delete": { "tags": [ "Webhooks" ], "summary": "Remove a Webhook", "description": "Removes the Webhook and its delivery log. The Identity's signing secret stays, for its other Webhooks.", "operationId": "DeleteWebhook", "parameters": [ { "name": "handle", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No Content" }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "api_key": [ ] } ] } }, "/api/identities/{handle}/webhooks/signing-key": { "post": { "tags": [ "Webhooks" ], "summary": "Rotate the Identity's signing secret", "description": "Replaces the secret every delivery to this Identity's Webhooks is signed with, effective from the next attempt. The response is the only place the new secret is ever shown.", "operationId": "RotateWebhookSigningKey", "parameters": [ { "name": "handle", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SigningKeyResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "api_key": [ ] } ] } }, "/api/identities/{handle}/webhooks/{id}/deliveries": { "get": { "tags": [ "Webhooks" ], "summary": "The Webhook's delivery log", "description": "Deliveries newest first, each with its attempts – when, how long, which HTTP status or error. Bounded by limit and nothing else: a delivery log is a window on what is happening now, and one Webhook's log is bounded by the retry schedule below rather than by how long the Identity has existed. The list that has to reach every row is GET /api/events, and that one takes a cursor. Failed deliveries retry after 30s, 5m, 30m, 2h, 6h and 24h – seven attempts in all – then the delivery is marked failed.", "operationId": "ListWebhookDeliveries", "parameters": [ { "name": "handle", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryListResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "api_key": [ ] } ] } }, "/api/vault/secrets": { "get": { "tags": [ "Vault" ], "summary": "List a namespace's secrets", "description": "Metadata only – name, type, size and dates. No value is ever in a list. The namespace is the caller's own scope unless identity names one: an Admin Key or a console session addresses the Org's namespace, an Identity Key its own Identity's. An Identity Key cannot reach another Identity's namespace or the Org's.", "operationId": "ListVaultSecrets", "parameters": [ { "name": "identity", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaultSecretListResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "api_key": [ ] } ] } }, "/api/vault/secrets/{name}": { "get": { "tags": [ "Vault" ], "summary": "One secret's metadata", "description": "What the list shows for one name. The value is at GET /api/vault/secrets/{name}/value. The namespace is the caller's own scope unless identity names one: an Admin Key or a console session addresses the Org's namespace, an Identity Key its own Identity's. An Identity Key cannot reach another Identity's namespace or the Org's.", "operationId": "GetVaultSecret", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "identity", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaultSecretView" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "api_key": [ ] } ] }, "put": { "tags": [ "Vault" ], "summary": "Write a secret", "description": "Creates the name or replaces what it held; 201 the first time, 200 after. The value is sealed with the Org's data key before it reaches the database and is never logged, listed, or echoed in an error. The namespace is the caller's own scope unless identity names one: an Admin Key or a console session addresses the Org's namespace, an Identity Key its own Identity's. An Identity Key cannot reach another Identity's namespace or the Org's.", "operationId": "SetVaultSecret", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "identity", "in": "query", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetSecretRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaultSecretView" } } } }, "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaultSecretView" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "api_key": [ ] } ] }, "delete": { "tags": [ "Vault" ], "summary": "Remove a secret", "description": "Immediate and irreversible: the row goes, and with it the only copy of the value. The namespace is the caller's own scope unless identity names one: an Admin Key or a console session addresses the Org's namespace, an Identity Key its own Identity's. An Identity Key cannot reach another Identity's namespace or the Org's.", "operationId": "DeleteVaultSecret", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "identity", "in": "query", "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "api_key": [ ] } ] } }, "/api/vault/secrets/{name}/value": { "get": { "tags": [ "Vault" ], "summary": "Read a secret's value", "description": "The one endpoint that returns a plaintext, and the one an agent calls when it needs the credential to act. Tigby can decrypt: the Vault is application-layer encrypted, not zero-knowledge. The namespace is the caller's own scope unless identity names one: an Admin Key or a console session addresses the Org's namespace, an Identity Key its own Identity's. An Identity Key cannot reach another Identity's namespace or the Org's.", "operationId": "RevealVaultSecret", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "identity", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaultSecretValueResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "api_key": [ ] } ] } }, "/api/identities/{handle}/connectors": { "get": { "tags": [ "Connectors" ], "summary": "List an Identity's Connectors", "description": "The third-party accounts this Identity acts through, and whether they are all stopped.", "operationId": "ListConnectors", "parameters": [ { "name": "handle", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorListResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "api_key": [ ] } ] }, "patch": { "tags": [ "Connectors" ], "summary": "Stop or restart every Connector of an Identity", "description": "The kill switch one level up: stopped, nothing goes out on any platform and nothing is polled, and every credential is kept. Per-Connector stopping is PATCH on the Connector itself.", "operationId": "PauseConnectors", "parameters": [ { "name": "handle", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PauseRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorListResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "api_key": [ ] } ] } }, "/api/identities/{handle}/connectors/{platform}": { "get": { "tags": [ "Connectors" ], "summary": "One Connector", "operationId": "GetConnector", "parameters": [ { "name": "handle", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "platform", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorView" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "api_key": [ ] } ] }, "put": { "tags": [ "Connectors" ], "summary": "Connect an account with an app password", "description": "The headless path: an agent hands in the account's handle and an app password – never the account's own password – and Tigby seals it under the Org's Vault key. The Console path is POST .../authorize, which is OAuth and does not put a password into Tigby at all. An account may only be connected once its profile says it is automated (AI Act Art. 50 and, as practically, the instance rules that defederate whole servers over undisclosed bots). Anything saying bot, automated or AI counts, so a customer's own wording is kept; send apply_disclosure: true and Tigby appends its line instead. There is no opt-out, and the poll worker re-asserts the labelling.", "operationId": "ConnectConnector", "parameters": [ { "name": "handle", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "platform", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorView" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "api_key": [ ] } ] }, "patch": { "tags": [ "Connectors" ], "summary": "Stop or restart one Connector", "description": "Refuses every outbound call and stops the polling; the credential stays where it is.", "operationId": "PauseConnector", "parameters": [ { "name": "handle", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "platform", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PauseRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorView" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "api_key": [ ] } ] }, "delete": { "tags": [ "Connectors" ], "summary": "Disconnect an account", "description": "Revokes the credential at the platform where the platform has a revoke, then deletes the row – which holds the only copy Tigby has of it.", "operationId": "DisconnectConnector", "parameters": [ { "name": "handle", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "platform", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "api_key": [ ] } ] } }, "/api/identities/{handle}/connectors/{platform}/authorize": { "post": { "tags": [ "Connectors" ], "summary": "Start the Console OAuth connect", "description": "Mints the redirect the customer's browser follows. The platform sends them back to the console, which posts the query string to POST /api/connectors/callback. No password ever reaches Tigby on this path. On Mastodon the answer also carries the instance's own rules, read from it here, to be shown before the customer authorises.", "operationId": "AuthorizeConnector", "parameters": [ { "name": "handle", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "platform", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizeRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizeResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "api_key": [ ] } ] } }, "/api/identities/{handle}/connectors/{platform}/posts": { "post": { "tags": [ "Connectors" ], "summary": "Post, or reply to a post", "description": "One verb for both: reply_to makes it a reply. Platform specifics ride options.{platform} – Bluesky takes langs and tags, Mastodon visibility, spoiler_text, sensitive and language – and an unknown key is refused rather than dropped. Every post passes the Policy Point first: the kill switch, the disclosure, and the Org's 24-hour cap. An Idempotency-Key header rides along to the platform where the platform has one, so a retried call does not become a second post.", "operationId": "CreateConnectorPost", "parameters": [ { "name": "handle", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "platform", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorPostRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorItemView" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "502": { "description": "Bad Gateway", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "api_key": [ ] } ] }, "get": { "tags": [ "Connectors" ], "summary": "Read the connected account's own posts", "operationId": "ListConnectorPosts", "parameters": [ { "name": "handle", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "platform", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorFeedResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "502": { "description": "Bad Gateway", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "api_key": [ ] } ] } }, "/api/identities/{handle}/connectors/{platform}/dms": { "post": { "tags": [ "Connectors" ], "summary": "Send a direct message", "description": "A capability, not a verb every platform has: Mastodon carries direct messages and Bluesky does not, so this answers connector_capability_unsupported there. On Mastodon a direct message is a status only its recipient sees, and to is the address it is delivered to. It passes the Policy Point like a post.", "operationId": "SendConnectorDirectMessage", "parameters": [ { "name": "handle", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "platform", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorDirectRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorItemView" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "502": { "description": "Bad Gateway", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "api_key": [ ] } ] }, "get": { "tags": [ "Connectors" ], "summary": "Read the account's direct-message conversations", "description": "The newest message of each conversation, newest first. The same capability as sending one, and the same refusal where the platform has none.", "operationId": "ListConnectorDirectMessages", "parameters": [ { "name": "handle", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "platform", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorFeedResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "502": { "description": "Bad Gateway", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "api_key": [ ] } ] } }, "/api/identities/{handle}/connectors/{platform}/thread": { "get": { "tags": [ "Connectors" ], "summary": "Read a post and what answers it", "description": "Takes the uri a read or an Event gave you. Posts that are deleted or not visible are simply absent.", "operationId": "ReadConnectorThread", "parameters": [ { "name": "handle", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "platform", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "uri", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorFeedResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "502": { "description": "Bad Gateway", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "api_key": [ ] } ] } }, "/api/identities/{handle}/connectors/{platform}/notifications": { "get": { "tags": [ "Connectors" ], "summary": "Read what has happened to the connected account", "description": "The same mentions, replies and – where the platform has them – direct messages the poll worker turns into connector.mention, connector.reply and connector.dm Events. Reading here does not consume them: a Webhook is the way to be told, this is the way to look.", "operationId": "ListConnectorNotifications", "parameters": [ { "name": "handle", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "platform", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorNotificationListResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "502": { "description": "Bad Gateway", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "api_key": [ ] } ] } }, "/api/connectors/callback": { "post": { "tags": [ "Connectors" ], "summary": "Finish the Console OAuth connect", "description": "The console posts the query string the platform sent it back with. The run is found by its state, used once, and deleted – a replayed callback finds nothing. An account may only be connected once its profile says it is automated (AI Act Art. 50 and, as practically, the instance rules that defederate whole servers over undisclosed bots). Anything saying bot, automated or AI counts, so a customer's own wording is kept; send apply_disclosure: true and Tigby appends its line instead. There is no opt-out, and the poll worker re-asserts the labelling.", "operationId": "CompleteConnectorAuthorization", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallbackRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorView" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "api_key": [ ] } ] } }, "/api/connectors/{platform}/client-metadata.json": { "get": { "tags": [ "Connectors" ], "summary": "The OAuth client-metadata document", "description": "What an AT Protocol authorization server fetches to learn who this client is. Public by protocol – the document's own URL is the client id. Bluesky's alone: Mastodon has one client per instance, registered at connect, so there is no document to serve.", "operationId": "ConnectorClientMetadata", "parameters": [ { "name": "platform", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonObject" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/api/exports": { "post": { "tags": [ "Exports" ], "summary": "Start an export", "description": "Art. 15 and 20 in one call. Answers 202 with the run; poll GET /api/exports/{id} until status is ready, or subscribe a Webhook to export.ready. The archive is a zip: a manifest, the account as JSON, and per Identity the Mailbox as mbox with a JSON manifest beside it. It is encrypted at rest under the Org's Vault key and deleted when it expires. An Identity Key may export its own Identity; Vault values are Org scope and off unless asked for.", "operationId": "CreateExport", "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CreateExportRequest" } ] } } } }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportView" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "api_key": [ ] } ] }, "get": { "tags": [ "Exports" ], "summary": "List export runs", "description": "Newest first. An Identity Key sees the runs of its own Identity; Org scope sees all of them.", "operationId": "ListExports", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportListResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "api_key": [ ] } ] } }, "/api/exports/{id}": { "get": { "tags": [ "Exports" ], "summary": "An export run", "description": "The run's status, and – once it is ready – its size, its SHA-256 and where to download it.", "operationId": "GetExport", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportView" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "api_key": [ ] } ] } }, "/api/exports/{id}/download": { "get": { "tags": [ "Exports" ], "summary": "Download the archive", "description": "The zip itself, authenticated like every other call – there is no unguarded link. Gone once the run expires.", "operationId": "DownloadExport", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The export archive.", "content": { "application/zip": { "schema": { "type": "string", "format": "binary" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "api_key": [ ] } ] } } }, "components": { "schemas": { "AccountDeletionView": { "required": [ "erasure_id", "requested_at", "identities", "note" ], "type": "object", "properties": { "erasure_id": { "type": "string", "format": "uuid" }, "requested_at": { "type": "string", "format": "date-time" }, "identities": { "type": "array", "items": { "type": "string" } }, "note": { "type": "string" } } }, "AddAllowedRecipientRequest": { "required": [ "value" ], "type": "object", "properties": { "value": { "type": [ "null", "string" ] } } }, "AllowedRecipientListResponse": { "required": [ "entries" ], "type": "object", "properties": { "entries": { "type": "array", "items": { "$ref": "#/components/schemas/AllowedRecipientView" } } } }, "AllowedRecipientView": { "required": [ "id", "scope", "kind", "value", "source", "created_at", "expired" ], "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "scope": { "type": "string" }, "handle": { "type": [ "null", "string" ] }, "kind": { "type": "string" }, "value": { "type": "string" }, "source": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "last_inbound_at": { "type": [ "null", "string" ], "format": "date-time" }, "expires_at": { "type": [ "null", "string" ], "format": "date-time" }, "expired": { "type": "boolean" } } }, "ApiKeyListResponse": { "required": [ "keys" ], "type": "object", "properties": { "keys": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKeyView" } } } }, "ApiKeyView": { "required": [ "id", "name", "scope", "token_prefix", "created_at" ], "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "scope": { "type": "string" }, "identity_id": { "type": [ "null", "string" ], "format": "uuid" }, "token_prefix": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "last_used_at": { "type": [ "null", "string" ], "format": "date-time" }, "revoked_at": { "type": [ "null", "string" ], "format": "date-time" } } }, "AttachmentInfo": { "required": [ "part_id", "type", "size" ], "type": "object", "properties": { "part_id": { "type": "string" }, "name": { "type": [ "null", "string" ] }, "type": { "type": "string" }, "size": { "type": "integer", "format": "int64" }, "disposition": { "type": [ "null", "string" ] }, "cid": { "type": [ "null", "string" ] } } }, "AuthorizeRequest": { "required": [ "account" ], "type": "object", "properties": { "account": { "type": [ "null", "string" ] } } }, "AuthorizeResponse": { "required": [ "authorization_url", "state", "expires_at", "instance_rules" ], "type": "object", "properties": { "authorization_url": { "type": "string" }, "state": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" }, "instance_rules": { "type": "array", "items": { "$ref": "#/components/schemas/InstanceRule" } } } }, "CallbackRequest": { "required": [ "callback", "apply_disclosure" ], "type": "object", "properties": { "callback": { "type": [ "null", "string" ] }, "apply_disclosure": { "type": [ "null", "boolean" ] } } }, "CallerView": { "required": [ "kind" ], "type": "object", "properties": { "kind": { "type": "string" }, "key_id": { "type": [ "null", "string" ], "format": "uuid" }, "key_name": { "type": [ "null", "string" ] }, "identity_id": { "type": [ "null", "string" ], "format": "uuid" }, "handle": { "type": [ "null", "string" ] } } }, "CardCapabilities": { "type": "object", "properties": { "streaming": { "type": "boolean", "default": false }, "push_notifications": { "type": "boolean", "default": false }, "extended_agent_card": { "type": "boolean", "default": false } } }, "CardDocument": { "required": [ "name", "description", "version", "capabilities", "default_input_modes", "default_output_modes", "interfaces", "skills" ], "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "version": { "type": "string" }, "documentation_url": { "type": [ "null", "string" ] }, "icon_url": { "type": [ "null", "string" ] }, "provider": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CardProvider" } ] }, "capabilities": { "$ref": "#/components/schemas/CardCapabilities" }, "default_input_modes": { "type": "array", "items": { "type": "string" } }, "default_output_modes": { "type": "array", "items": { "type": "string" } }, "interfaces": { "type": "array", "items": { "$ref": "#/components/schemas/CardInterface" } }, "skills": { "type": "array", "items": { "$ref": "#/components/schemas/CardSkill" } } } }, "CardInterface": { "required": [ "url", "protocol_binding", "protocol_version" ], "type": "object", "properties": { "url": { "type": "string" }, "protocol_binding": { "type": "string" }, "protocol_version": { "type": "string" }, "tenant": { "type": [ "null", "string" ] } } }, "CardProvider": { "required": [ "organization", "url" ], "type": "object", "properties": { "organization": { "type": "string" }, "url": { "type": "string" } } }, "CardResponse": { "required": [ "handle", "card", "agent_card", "agent_card_url", "profile_url", "updated_at" ], "type": "object", "properties": { "handle": { "type": "string" }, "card": { "$ref": "#/components/schemas/CardDocument" }, "agent_card": { "$ref": "#/components/schemas/JsonObject" }, "agent_card_url": { "type": "string" }, "profile_url": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } } }, "CardSkill": { "required": [ "id", "name", "description" ], "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": [ "null", "array" ], "items": { "type": "string" } }, "examples": { "type": [ "null", "array" ], "items": { "type": "string" } }, "input_modes": { "type": [ "null", "array" ], "items": { "type": "string" } }, "output_modes": { "type": [ "null", "array" ], "items": { "type": "string" } } } }, "ComponentHealth": { "required": [ "name", "status", "latency_ms" ], "type": "object", "properties": { "name": { "type": "string" }, "status": { "type": "string" }, "latency_ms": { "type": "number", "format": "double" }, "detail": { "type": [ "null", "string" ] } } }, "ConnectRequest": { "required": [ "account", "app_password", "apply_disclosure" ], "type": "object", "properties": { "account": { "type": [ "null", "string" ] }, "app_password": { "type": [ "null", "string" ] }, "apply_disclosure": { "type": [ "null", "boolean" ] } } }, "ConnectorDirectRequest": { "required": [ "to", "text", "reply_to", "options" ], "type": "object", "properties": { "to": { "type": [ "null", "string" ] }, "text": { "type": [ "null", "string" ] }, "reply_to": { "type": [ "null", "string" ] }, "options": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/JsonObject" } ] } } }, "ConnectorFeedResponse": { "required": [ "posts" ], "type": "object", "properties": { "posts": { "type": "array", "items": { "$ref": "#/components/schemas/ConnectorItemView" } }, "cursor": { "type": [ "null", "string" ] } } }, "ConnectorItemView": { "required": [ "uri", "author_id", "author", "text", "created_at" ], "type": "object", "properties": { "uri": { "type": "string" }, "url": { "type": [ "null", "string" ] }, "author_id": { "type": "string" }, "author": { "type": "string" }, "author_name": { "type": [ "null", "string" ] }, "text": { "type": "string" }, "reply_to": { "type": [ "null", "string" ] }, "created_at": { "type": "string", "format": "date-time" } } }, "ConnectorListResponse": { "required": [ "connectors", "paused" ], "type": "object", "properties": { "connectors": { "type": "array", "items": { "$ref": "#/components/schemas/ConnectorView" } }, "paused": { "type": "boolean" } } }, "ConnectorNotificationListResponse": { "required": [ "notifications" ], "type": "object", "properties": { "notifications": { "type": "array", "items": { "$ref": "#/components/schemas/ConnectorNotificationView" } }, "cursor": { "type": [ "null", "string" ] } } }, "ConnectorNotificationView": { "required": [ "kind", "post", "at" ], "type": "object", "properties": { "kind": { "type": "string" }, "post": { "$ref": "#/components/schemas/ConnectorItemView" }, "at": { "type": "string", "format": "date-time" } } }, "ConnectorPostRequest": { "required": [ "text", "reply_to", "options" ], "type": "object", "properties": { "text": { "type": [ "null", "string" ] }, "reply_to": { "type": [ "null", "string" ] }, "options": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/JsonObject" } ] } } }, "ConnectorView": { "required": [ "platform", "status", "account", "account_id", "service", "connected_via", "capabilities", "disclosed", "paused", "created_at", "updated_at" ], "type": "object", "properties": { "platform": { "type": "string" }, "status": { "type": "string" }, "account": { "type": "string" }, "account_id": { "type": "string" }, "service": { "type": "string" }, "connected_via": { "type": "string" }, "capabilities": { "type": "array", "items": { "type": "string" } }, "disclosed": { "type": "boolean" }, "paused": { "type": "boolean" }, "polled_at": { "type": [ "null", "string" ], "format": "date-time" }, "last_error": { "type": [ "null", "string" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "ConsumeMagicLinkRequest": { "required": [ "token" ], "type": "object", "properties": { "token": { "type": [ "null", "string" ] } } }, "ConsumeMagicLinkResponse": { "required": [ "session_token", "session", "org" ], "type": "object", "properties": { "session_token": { "type": "string" }, "session": { "$ref": "#/components/schemas/SessionView" }, "org": { "$ref": "#/components/schemas/OrgView" } } }, "ContactRequest": { "required": [ "name", "email", "message", "language" ], "type": "object", "properties": { "name": { "type": [ "null", "string" ] }, "email": { "type": [ "null", "string" ] }, "message": { "type": [ "null", "string" ] }, "language": { "type": [ "null", "string" ] } } }, "CreateApiKeyRequest": { "required": [ "name" ], "type": "object", "properties": { "name": { "type": [ "null", "string" ] } } }, "CreateExportRequest": { "required": [ "scope", "handle", "include_secret_values" ], "type": "object", "properties": { "scope": { "type": [ "null", "string" ] }, "handle": { "type": [ "null", "string" ] }, "include_secret_values": { "type": [ "null", "boolean" ] } } }, "CreateIdentityRequest": { "required": [ "handle" ], "type": "object", "properties": { "handle": { "type": [ "null", "string" ] } } }, "CreateWebhookRequest": { "required": [ "url", "event_types" ], "type": "object", "properties": { "url": { "type": [ "null", "string" ] }, "event_types": { "type": [ "null", "array" ], "items": { "type": "string" } } } }, "CreatedApiKeyResponse": { "required": [ "key", "api_key" ], "type": "object", "properties": { "key": { "type": "string" }, "api_key": { "$ref": "#/components/schemas/ApiKeyView" } } }, "CurrentSessionResponse": { "required": [ "session", "org", "tos" ], "type": "object", "properties": { "session": { "$ref": "#/components/schemas/SessionView" }, "org": { "$ref": "#/components/schemas/OrgView" }, "tos": { "$ref": "#/components/schemas/TosStatusView" } } }, "DeleteAccountRequest": { "required": [ "confirm" ], "type": "object", "properties": { "confirm": { "type": [ "null", "string" ] } } }, "DeliveryAttemptView": { "required": [ "attempt", "requested_at", "duration_ms" ], "type": "object", "properties": { "attempt": { "type": "integer", "format": "int32" }, "requested_at": { "type": "string", "format": "date-time" }, "duration_ms": { "type": "integer", "format": "int32" }, "response_status": { "type": [ "null", "integer" ], "format": "int32" }, "error": { "type": [ "null", "string" ] } } }, "DeliveryListResponse": { "required": [ "deliveries" ], "type": "object", "properties": { "deliveries": { "type": "array", "items": { "$ref": "#/components/schemas/DeliveryView" } } } }, "DeliveryView": { "required": [ "id", "event_id", "event_type", "status", "is_replay", "attempt_count", "created_at", "attempts" ], "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "event_id": { "type": "string" }, "event_type": { "type": "string" }, "status": { "type": "string" }, "is_replay": { "type": "boolean" }, "attempt_count": { "type": "integer", "format": "int32" }, "created_at": { "type": "string", "format": "date-time" }, "next_attempt_at": { "type": [ "null", "string" ], "format": "date-time" }, "completed_at": { "type": [ "null", "string" ], "format": "date-time" }, "attempts": { "type": "array", "items": { "$ref": "#/components/schemas/DeliveryAttemptView" } } } }, "DeviceAuthorizationView": { "required": [ "user_code", "name", "status", "created_at", "expires_at" ], "type": "object", "properties": { "user_code": { "type": "string" }, "name": { "type": "string" }, "client": { "type": [ "null", "string" ] }, "status": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" } } }, "DeviceTokenRequest": { "required": [ "device_code" ], "type": "object", "properties": { "device_code": { "type": [ "null", "string" ] } } }, "DeviceTokenResponse": { "required": [ "key", "api_key" ], "type": "object", "properties": { "key": { "type": "string" }, "api_key": { "$ref": "#/components/schemas/ApiKeyView" } } }, "DisclosureRequest": { "required": [ "enabled", "acknowledge_warning" ], "type": "object", "properties": { "enabled": { "type": [ "null", "boolean" ] }, "acknowledge_warning": { "type": [ "null", "boolean" ] } } }, "DisclosureResponse": { "required": [ "enabled", "footer", "warning" ], "type": "object", "properties": { "enabled": { "type": "boolean" }, "footer": { "type": "string" }, "warning": { "type": "string" } } }, "EventListResponse": { "required": [ "events" ], "type": "object", "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/EventView" } }, "next_cursor": { "type": [ "null", "string" ] } } }, "EventView": { "required": [ "id", "type", "payload", "created_at" ], "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "handle": { "type": [ "null", "string" ] }, "payload": { "$ref": "#/components/schemas/JsonObject" }, "created_at": { "type": "string", "format": "date-time" } } }, "ExportListResponse": { "required": [ "exports" ], "type": "object", "properties": { "exports": { "type": "array", "items": { "$ref": "#/components/schemas/ExportView" } } } }, "ExportView": { "required": [ "id", "scope", "status", "secret_values", "requested_at", "expires_at" ], "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "scope": { "type": "string" }, "handle": { "type": [ "null", "string" ] }, "status": { "type": "string" }, "secret_values": { "type": "string" }, "bytes": { "type": [ "null", "integer" ], "format": "int64" }, "sha256": { "type": [ "null", "string" ] }, "file_name": { "type": [ "null", "string" ] }, "download_url": { "type": [ "null", "string" ] }, "error": { "type": [ "null", "string" ] }, "requested_at": { "type": "string", "format": "date-time" }, "ready_at": { "type": [ "null", "string" ], "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" } } }, "HandleAvailabilityResponse": { "required": [ "available" ], "type": "object", "properties": { "handle": { "type": [ "null", "string" ] }, "available": { "type": "boolean" }, "code": { "type": [ "null", "string" ] }, "detail": { "type": [ "null", "string" ] }, "email": { "type": [ "null", "string" ] }, "profile_url": { "type": [ "null", "string" ] }, "tunnel_host": { "type": [ "null", "string" ] } } }, "HealthReport": { "required": [ "status", "service", "version", "checked_at", "components" ], "type": "object", "properties": { "status": { "type": "string" }, "service": { "type": "string" }, "version": { "type": "string" }, "checked_at": { "type": "string", "format": "date-time" }, "components": { "type": "array", "items": { "$ref": "#/components/schemas/ComponentHealth" } } } }, "HitRequest": { "required": [ "host", "path", "lang" ], "type": "object", "properties": { "host": { "type": [ "null", "string" ] }, "path": { "type": [ "null", "string" ] }, "lang": { "type": [ "null", "string" ] } } }, "IdentityListResponse": { "required": [ "identities" ], "type": "object", "properties": { "identities": { "type": "array", "items": { "$ref": "#/components/schemas/IdentityView" } } } }, "IdentityResponse": { "required": [ "identity", "saga" ], "type": "object", "properties": { "identity": { "$ref": "#/components/schemas/IdentityView" }, "saga": { "$ref": "#/components/schemas/SagaView" }, "tunnel": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TunnelView" } ] }, "onboarding": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OnboardingView" } ] } } }, "IdentitySecretsResponse": { "type": "object", "properties": { "identity_key": { "type": [ "null", "string" ] }, "mailbox": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/MailboxCredentials" } ] } } }, "IdentityView": { "required": [ "id", "handle", "status", "email", "profile_url", "tunnel_host", "created_at" ], "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "handle": { "type": "string" }, "status": { "type": "string" }, "email": { "type": "string" }, "profile_url": { "type": "string" }, "tunnel_host": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "ready_at": { "type": [ "null", "string" ], "format": "date-time" } } }, "InstanceRule": { "required": [ "id", "text" ], "type": "object", "properties": { "id": { "type": "string" }, "text": { "type": "string" }, "hint": { "type": [ "null", "string" ] } } }, "JsonObject": { "type": "object" }, "MagicLinkRequest": { "required": [ "email", "language", "tos_accepted" ], "type": "object", "properties": { "email": { "type": [ "null", "string" ] }, "language": { "type": [ "null", "string" ], "default": "en" }, "tos_accepted": { "type": [ "null", "boolean" ] }, "invite_code": { "type": [ "null", "string" ] } } }, "MagicLinkResponse": { "required": [ "status", "expires_at" ], "type": "object", "properties": { "status": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" }, "dev_magic_link": { "type": [ "null", "string" ] } } }, "MailAddress": { "required": [ "email" ], "type": "object", "properties": { "name": { "type": [ "null", "string" ] }, "email": { "type": "string" } } }, "MailPauseRequest": { "required": [ "paused" ], "type": "object", "properties": { "paused": { "type": [ "null", "boolean" ] } } }, "MailStatusResponse": { "required": [ "paused" ], "type": "object", "properties": { "paused": { "type": "boolean" }, "paused_at": { "type": [ "null", "string" ], "format": "date-time" } } }, "MailboxCredentials": { "required": [ "imap_host", "imap_port", "imap_security", "username", "password" ], "type": "object", "properties": { "imap_host": { "type": "string" }, "imap_port": { "type": "integer", "format": "int32" }, "imap_security": { "type": "string" }, "username": { "type": "string" }, "password": { "type": "string" } } }, "MailboxPasswordResponse": { "required": [ "mailbox" ], "type": "object", "properties": { "mailbox": { "$ref": "#/components/schemas/MailboxCredentials" } } }, "MessageDetail": { "required": [ "id", "received_at", "message_id", "in_reply_to", "references", "from", "reply_to", "to", "cc", "attachments", "size", "unread", "origin" ], "type": "object", "properties": { "id": { "type": "string" }, "received_at": { "type": "string", "format": "date-time" }, "sent_at": { "type": [ "null", "string" ], "format": "date-time" }, "message_id": { "type": "array", "items": { "type": "string" } }, "in_reply_to": { "type": "array", "items": { "type": "string" } }, "references": { "type": "array", "items": { "type": "string" } }, "from": { "type": "array", "items": { "$ref": "#/components/schemas/MailAddress" } }, "reply_to": { "type": "array", "items": { "$ref": "#/components/schemas/MailAddress" } }, "to": { "type": "array", "items": { "$ref": "#/components/schemas/MailAddress" } }, "cc": { "type": "array", "items": { "$ref": "#/components/schemas/MailAddress" } }, "subject": { "type": [ "null", "string" ] }, "text_body": { "type": [ "null", "string" ] }, "html_body": { "type": [ "null", "string" ] }, "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/AttachmentInfo" } }, "size": { "type": "integer", "format": "int64" }, "unread": { "type": "boolean" }, "delivered_to": { "type": [ "null", "string" ] }, "tag": { "type": [ "null", "string" ] }, "origin": { "$ref": "#/components/schemas/OriginVerdict" }, "authentication_results": { "type": [ "null", "string" ] } } }, "MessageListResponse": { "required": [ "messages", "total", "offset", "limit" ], "type": "object", "properties": { "messages": { "type": "array", "items": { "$ref": "#/components/schemas/MessageSummary" } }, "total": { "type": "integer", "format": "int64" }, "offset": { "type": "integer", "format": "int32" }, "limit": { "type": "integer", "format": "int32" } } }, "MessageSummary": { "required": [ "id", "received_at", "from", "to", "size", "has_attachment", "unread", "origin" ], "type": "object", "properties": { "id": { "type": "string" }, "received_at": { "type": "string", "format": "date-time" }, "from": { "type": "array", "items": { "$ref": "#/components/schemas/MailAddress" } }, "to": { "type": "array", "items": { "$ref": "#/components/schemas/MailAddress" } }, "subject": { "type": [ "null", "string" ] }, "preview": { "type": [ "null", "string" ] }, "size": { "type": "integer", "format": "int64" }, "has_attachment": { "type": "boolean" }, "unread": { "type": "boolean" }, "delivered_to": { "type": [ "null", "string" ] }, "tag": { "type": [ "null", "string" ] }, "origin": { "$ref": "#/components/schemas/OriginVerdict" } } }, "OnboardingView": { "required": [ "started_at", "ready_at", "seconds" ], "type": "object", "properties": { "started_at": { "type": "string", "format": "date-time" }, "ready_at": { "type": "string", "format": "date-time" }, "seconds": { "type": "number", "format": "double" } } }, "OrgView": { "required": [ "id", "email", "language", "tos_version", "tos_accepted_at", "created_at" ], "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "email": { "type": "string" }, "language": { "type": "string" }, "tos_version": { "type": "string" }, "tos_accepted_at": { "type": "string", "format": "date-time" }, "email_verified_at": { "type": [ "null", "string" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } } }, "OriginVerdict": { "required": [ "basis", "passed" ], "type": "object", "properties": { "dmarc": { "type": [ "null", "string" ] }, "spf": { "type": [ "null", "string" ] }, "basis": { "type": "string" }, "passed": { "type": "boolean" } } }, "PauseRequest": { "required": [ "paused" ], "type": "object", "properties": { "paused": { "type": [ "null", "boolean" ] } } }, "ProblemDetails": { "title": "Problem", "required": [ "type", "title", "status", "detail", "code", "doc_url", "agent_hint" ], "type": "object", "properties": { "type": { "type": "string", "description": "Identifies the problem type: https://tigby.eu/problems/{code}. Not a documentation page.", "format": "uri" }, "title": { "type": "string", "description": "The problem in a few words, for a human. Not stable – branch on code instead." }, "status": { "type": "integer", "description": "The HTTP status code, repeated in the body.", "format": "int32" }, "detail": { "type": "string", "description": "What went wrong with this request, in one sentence." }, "instance": { "type": "string", "description": "The path the request was made to. Absent when the error has no request to point at." }, "code": { "type": "string", "description": "The stable machine-readable error code, e.g. handle_taken. Safe to branch on; the title and detail are not." }, "doc_url": { "type": "string", "description": "Where the code is documented for a human: https://docs.tigby.eu/errors/{code}.", "format": "uri" }, "agent_hint": { "type": "string", "description": "What an autonomous caller should do next: retry, back off, fix the request, or stop. One sentence, written for an agent rather than for a log reader." } }, "description": "An RFC 9457 problem detail. Every error Tigby produces carries code, doc_url and agent_hint on top of the standard members." }, "ProfileResponse": { "required": [ "handle", "status", "language", "name", "description", "email", "profile_url", "tunnel_host", "agent_card_url", "protocol_version", "created_at", "skills", "agent_card" ], "type": "object", "properties": { "handle": { "type": "string" }, "status": { "type": "string" }, "language": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "organization": { "type": [ "null", "string" ] }, "email": { "type": "string" }, "profile_url": { "type": "string" }, "tunnel_host": { "type": "string" }, "agent_card_url": { "type": "string" }, "protocol_version": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "skills": { "type": "array", "items": { "$ref": "#/components/schemas/ProfileSkill" } }, "agent_card": { "$ref": "#/components/schemas/JsonObject" } } }, "ProfileSkill": { "required": [ "id", "name", "description" ], "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" } } }, "ReplayRequest": { "required": [ "webhook_id" ], "type": "object", "properties": { "webhook_id": { "type": [ "null", "string" ], "format": "uuid" } } }, "ReplayResponse": { "required": [ "delivery_id" ], "type": "object", "properties": { "delivery_id": { "type": "string", "format": "uuid" } } }, "SagaStepView": { "required": [ "name", "status", "attempts" ], "type": "object", "properties": { "name": { "type": "string" }, "status": { "type": "string" }, "attempts": { "type": "integer", "format": "int32" }, "error": { "type": [ "null", "string" ] }, "started_at": { "type": [ "null", "string" ], "format": "date-time" }, "finished_at": { "type": [ "null", "string" ], "format": "date-time" } } }, "SagaView": { "required": [ "id", "kind", "status", "steps", "created_at", "updated_at" ], "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string" }, "status": { "type": "string" }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/SagaStepView" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "finished_at": { "type": [ "null", "string" ], "format": "date-time" }, "next_attempt_at": { "type": [ "null", "string" ], "format": "date-time" } } }, "SendRequest": { "required": [ "to", "cc", "bcc", "subject", "text", "html", "in_reply_to", "references" ], "type": "object", "properties": { "to": { "type": [ "null", "array" ], "items": { "type": "string" } }, "cc": { "type": [ "null", "array" ], "items": { "type": "string" } }, "bcc": { "type": [ "null", "array" ], "items": { "type": "string" } }, "subject": { "type": [ "null", "string" ] }, "text": { "type": [ "null", "string" ] }, "html": { "type": [ "null", "string" ] }, "in_reply_to": { "type": [ "null", "string" ] }, "references": { "type": [ "null", "array" ], "items": { "type": "string" } } } }, "SendResponse": { "required": [ "message_id", "recipients", "disclosure" ], "type": "object", "properties": { "message_id": { "type": "string" }, "recipients": { "type": "array", "items": { "type": "string" } }, "disclosure": { "type": "boolean" } } }, "SessionView": { "required": [ "id", "expires_at", "created_at" ], "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "expires_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } } }, "SetSecretRequest": { "required": [ "value", "description" ], "type": "object", "properties": { "value": { "type": [ "null", "string" ] }, "description": { "type": [ "null", "string" ] } } }, "SigningKeyResponse": { "required": [ "signing_secret" ], "type": "object", "properties": { "signing_secret": { "type": "string" } } }, "StartDeviceRequest": { "required": [ "name", "client" ], "type": "object", "properties": { "name": { "type": [ "null", "string" ] }, "client": { "type": [ "null", "string" ] } } }, "StartDeviceResponse": { "required": [ "device_code", "user_code", "verification_uri", "verification_uri_complete", "expires_at", "interval_seconds" ], "type": "object", "properties": { "device_code": { "type": "string" }, "user_code": { "type": "string" }, "verification_uri": { "type": "string" }, "verification_uri_complete": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" }, "interval_seconds": { "type": "integer", "format": "int32" } } }, "TosAcceptanceRequest": { "required": [ "version" ], "type": "object", "properties": { "version": { "type": [ "null", "string" ] } } }, "TosStatusView": { "required": [ "current_version", "accepted_version", "accepted_at", "gated" ], "type": "object", "properties": { "current_version": { "type": "string" }, "accepted_version": { "type": "string" }, "accepted_at": { "type": "string", "format": "date-time" }, "effective_at": { "type": [ "null", "string" ], "format": "date-time" }, "gated": { "type": "boolean" } } }, "TunnelView": { "required": [ "host", "connect_url" ], "type": "object", "properties": { "host": { "type": "string" }, "tcp_port": { "type": [ "null", "integer" ], "format": "int32" }, "sni_port": { "type": [ "null", "integer" ], "format": "int32" }, "connect_url": { "type": "string" } } }, "UpdateWebhookRequest": { "required": [ "url", "event_types" ], "type": "object", "properties": { "url": { "type": [ "null", "string" ] }, "event_types": { "type": [ "null", "array" ], "items": { "type": "string" } } } }, "VaultSecretListResponse": { "required": [ "secrets" ], "type": "object", "properties": { "secrets": { "type": "array", "items": { "$ref": "#/components/schemas/VaultSecretView" } } } }, "VaultSecretValueResponse": { "required": [ "name", "value" ], "type": "object", "properties": { "name": { "type": "string" }, "identity": { "type": [ "null", "string" ] }, "value": { "type": "string" } } }, "VaultSecretView": { "required": [ "name", "type", "bytes", "created_at", "updated_at" ], "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" }, "identity": { "type": [ "null", "string" ] }, "description": { "type": [ "null", "string" ] }, "bytes": { "type": "integer", "format": "int32" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "WebhookListResponse": { "required": [ "webhooks" ], "type": "object", "properties": { "webhooks": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookView" } } } }, "WebhookView": { "required": [ "id", "handle", "url", "event_types", "created_at" ], "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "handle": { "type": "string" }, "url": { "type": "string" }, "event_types": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string", "format": "date-time" }, "signing_secret": { "type": [ "null", "string" ] } } }, "WhoamiResponse": { "required": [ "org", "caller" ], "type": "object", "properties": { "org": { "$ref": "#/components/schemas/OrgView" }, "caller": { "$ref": "#/components/schemas/CallerView" } } } }, "securitySchemes": { "api_key": { "type": "http", "description": "An Admin Key (tigby_admin_…) for Org-level calls, an Identity Key (tigby_id_…) for one Identity's own resources, or a console session (tigby_sess_…). Sent as Authorization: Bearer .", "scheme": "bearer" } } }, "tags": [ { "name": "Health", "description": "Whether the API and the dependencies it needs can serve, as one status code and a component list." }, { "name": "Identities", "description": "Creating an Identity, following its provisioning saga, reading its parts, and deleting it." }, { "name": "A2A Card", "description": "The machine-readable agent card an Identity publishes, read and edited as a JSON Merge Patch." }, { "name": "Events", "description": "Everything Tigby records for the Org, paged newest first and replayable to a Webhook." }, { "name": "Account", "description": "The Org's own record, the Terms it is on, and the erasure that ends it." }, { "name": "Analytics", "description": "The page counter: one number per day, host, path and language, with no visitor in it." }, { "name": "Contact", "description": "The § 5 DDG contact form behind tigby.eu/contact: no credential, nothing stored, delivered to a person." }, { "name": "Auth", "description": "Magic-link sign-in, the console session it mints, and the CLI's device login." }, { "name": "API keys", "description": "Minting, listing and revoking Admin Keys. An Identity's own key is minted by its saga." }, { "name": "Mailbox", "description": "Reading an Identity's real mailbox over REST, and rotating its IMAP password." }, { "name": "Allowed recipients", "description": "Who an Identity may send mail to, per Org or per Identity. Nothing else goes out." }, { "name": "Outbound mail", "description": "Sending as an Identity through the one policy point, and the switches that stop it." }, { "name": "Webhooks", "description": "Signed delivery targets per Identity, and the log of what each delivery did." }, { "name": "Vault", "description": "The Org's encrypted secret store, in the Org's namespace or in one Identity's." }, { "name": "Connectors", "description": "Connecting an Identity to an account on Bluesky or Mastodon, and acting through it." }, { "name": "Exports", "description": "An archive of everything Tigby holds, for the Org or for one Identity, fetched once." } ] }