{"openapi":"3.1.0","info":{"title":"Agente Public API","version":"2026-08-28","summary":"Public API surface of the Agente web control plane — Agente Desktop licensing, auth, team directory, managed-model proxy, download, and support reporting.","description":"Agente is the digital team for CPA and accounting offices in the Israeli (Hebrew) market.\nAgente Desktop is a local-first Electron application that runs a Hermes agent runtime on the office computer, with MCP connector support, an A2A relay, a skills system, and internationalization (Hebrew default, plus English, Polish, Ukrainian, and Russian).\nThis web control plane (www.agente.dev) provides marketing, account, authentication, seat licensing, team directory, a managed-model proxy, and update/support-report surfaces for the Desktop app.\n\nTwo authentication styles are used:\n- **Desktop endpoints** authenticate with OIDC-style access tokens issued through the Desktop auth flow (`Authorization: Bearer <token>`).\n- **Account endpoints** (remote processing, download) use the browser session cookie established on www.agente.dev.\n\nAlso public and machine-readable: /llms.txt (plain-text agent guide), /developers (developer overview), /privacy-policy and /terms (legal). Update manifests (/latest.yml, /latest-mac.yml and the alpha and artifact family) serve the Desktop update feed and are plain YAML.\n\nVersioning and deprecation: the API is versioned in the URL path (for example /api/desktop/team-directory/v2 and /api/account/remote-processing/v1). A new major version ships as a new path and the previous path stays live until it is explicitly deprecated and sunset. Deprecation is announced on /developers and in this document before an endpoint is scheduled for removal, and deprecated endpoints carry `Deprecation` and `Sunset` (RFC 8594) response headers so clients can migrate before the sunset date. No public endpoint is deprecated today.","contact":{"name":"Agente","email":"leon@agente.dev"},"license":{"name":"Proprietary — see /terms"}},"servers":[{"url":"https://www.agente.dev","description":"Web control plane (production)"},{"url":"https://staging.agente.dev","description":"Web control plane (staging)"},{"url":"https://api.agente.dev","description":"API host (proxy/legacy alias)"}],"tags":[{"name":"Desktop licensing","description":"Entitlement validation and usage consumption for Agente Desktop."},{"name":"Desktop auth","description":"Token exchange and refresh for Desktop-to-control-plane authentication."},{"name":"Team directory","description":"Signed team-directory leases consumed by Desktop."},{"name":"Account","description":"Browser-session account surfaces: download and remote processing."},{"name":"Support","description":"Support-report ingestion."}],"paths":{"/api/desktop/license/validate":{"get":{"tags":["Desktop licensing"],"operationId":"validateDesktopLicense","summary":"Validate a Desktop entitlement","description":"Validates the bearer access token against the office subscription and returns the entitlement contract (v3 by default, v2-compatible dual emission). Acknowledges the carried entitlement contract version via `X-Agente-Entitlement-Acknowledged` (2 or 3).","security":[{"bearerAuth":[]}],"parameters":[{"name":"X-Agente-Entitlement-Acknowledged","in":"header","required":false,"schema":{"type":"integer","enum":[2,3]},"description":"Entitlement contract version the caller supports."}],"responses":{"200":{"description":"Entitlement validation result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LicenseValidation"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/desktop/license/consume":{"post":{"tags":["Desktop licensing"],"operationId":"consumeDesktopLicense","summary":"Consume metered license capacity","description":"Consumes metered budget units (or acknowledges BYOK pilot usage) for an entitled Desktop installation.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LicenseConsumeRequest"}}}},"responses":{"200":{"description":"Consumption acknowledged with remaining capacity.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LicenseConsumeResponse"}}}},"400":{"description":"Invalid request body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/desktop/auth/exchange":{"post":{"tags":["Desktop auth"],"operationId":"exchangeDesktopAuthCode","summary":"Exchange a Desktop auth code for tokens","description":"Exchanges the short-lived auth code obtained from the Desktop sign-in flow for an access token and refresh token.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthExchangeRequest"}}}},"responses":{"200":{"description":"Token set.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenSet"}}}},"400":{"description":"Invalid request body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Code rejected or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/desktop/auth/refresh":{"post":{"tags":["Desktop auth"],"operationId":"refreshDesktopAuthTokens","summary":"Refresh a Desktop token set","description":"Exchanges a valid refresh token for a fresh access token and refresh token set, verifying the refresh token against the Desktop OIDC store and recording device usage for the session.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthRefreshRequest"}}}},"responses":{"200":{"description":"Fresh token set.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenSet"}}}},"400":{"description":"Invalid request body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Invalid or expired refresh token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/desktop/team-directory/v2":{"get":{"tags":["Team directory"],"operationId":"getTeamDirectoryV2","summary":"Fetch the signed team directory (v2)","description":"Returns the office team-directory snapshot signed as a directory lease. Lease token and expiry are also returned in the `X-Agente-Directory-Lease` and `X-Agente-Directory-Valid-Until` response headers.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Signed directory snapshot.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TeamDirectoryV2"}}}},"401":{"description":"Missing, invalid, or v1-contract token (`desktop_token_upgrade_required`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/desktop/team-directory/v1/jwks":{"get":{"tags":["Team directory"],"operationId":"getTeamDirectoryJwks","summary":"Public JWKS for verifying directory signatures","description":"Returns an RFC 7517 JSON Web Key Set whose public keys can be used to verify the signature on Desktop team-directory lease tokens. No authentication required.","responses":{"200":{"description":"JSON Web Key Set used to verify directory lease signatures.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JwksDocument"}}}},"503":{"description":"Directory signing unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/desktop/download":{"get":{"tags":["Account"],"operationId":"getDesktopDownload","summary":"Download Agente Desktop","description":"Returns the Desktop release payload for the authenticated office. Requires the browser session; redirects to the release asset when entitled.","security":[{"cookieAuth":[]}],"parameters":[{"name":"platform","in":"query","required":false,"schema":{"type":"string","enum":["mac","windows"]},"description":"Target platform. When omitted, the platform is inferred from the user-agent header."}],"responses":{"302":{"description":"Redirect to the release payload for the requested platform.","headers":{"Location":{"schema":{"type":"string","format":"uri"},"description":"URL of the Desktop release payload."}}},"400":{"description":"Unsupported or unrecognized platform.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DownloadError"}}}},"401":{"description":"Not signed in.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DownloadError"}}}},"402":{"description":"Subscription required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DownloadError"}}}},"500":{"description":"Entitlement lookup failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DownloadError"}}}},"503":{"description":"Release payload unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DownloadError"}}}}}}},"/api/account/remote-processing/v1":{"get":{"tags":["Account"],"operationId":"listRemoteProcessingRoutes","summary":"List managed-model remote-processing controls","description":"Lists the office’s managed-model remote-processing routes and their controls. Requires the browser session.","security":[{"cookieAuth":[]}],"responses":{"200":{"description":"Remote-processing control list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RemoteProcessingRoutesResponse"}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Admin role required for this office.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Route not found or not ready.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Revision conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Store unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/desktop/support-report/init":{"post":{"tags":["Support"],"operationId":"initSupportReport","summary":"Initialize a support report upload","description":"First step of filing a Desktop problem report: validates the occurrence id and bundle metadata and returns a short-lived, one-time upload target that Desktop PUTs the report bundle to directly. Only available while support reporting is enabled.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupportReportInitRequest"}}}},"responses":{"200":{"description":"Upload session initialized (or the occurrence was already filed; `already_filed: true` bodies carry the existing ticket instead of an upload target).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupportReportInitResponse"}}}},"400":{"description":"Invalid request body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Support reporting disabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"Bundle exceeds the maximum attachment size.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Upstream upload-target failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Support reporting not configured.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/desktop/support-report/complete":{"post":{"tags":["Support"],"operationId":"completeSupportReport","summary":"Complete and submit a support report","description":"Second step of filing a Desktop problem report: creates (or repairs) the support ticket once the bundle has been uploaded to the target handed out by the init step, attaching the report manifest and returning the ticket and attachment status. Idempotent per occurrence id.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupportReportCompleteRequest"}}}},"responses":{"200":{"description":"Support report submitted (existing ticket reused).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupportReportCompleteResponse"}}}},"201":{"description":"Support report submitted (new ticket created).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupportReportCompleteResponse"}}}},"400":{"description":"Invalid request body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Support reporting disabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Upstream ticket failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Support reporting not configured.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"OIDC-style Desktop access token issued via the Desktop auth flow."},"cookieAuth":{"type":"apiKey","in":"cookie","name":"agente_session","description":"Browser session cookie established on www.agente.dev."}},"schemas":{"ErrorResponse":{"type":"object","additionalProperties":true,"properties":{"error":{"type":"string","description":"Stable machine-readable error code."},"details":{"type":"object","additionalProperties":true,"description":"Validation field errors (present on 400s)."}}},"LicenseValidation":{"type":"object","additionalProperties":true,"properties":{"contract_version":{"type":"integer","enum":[2,3],"description":"Entitlement contract version emitted."},"valid":{"type":"boolean"},"org_id":{"type":["string","null"],"format":"uuid","description":"Office (client) id; null when invalid."},"plan":{"type":"string","enum":["free","paid","legacy"]},"license_state":{"type":"string","enum":["active","expired","invalid"]},"model_access":{"type":"string","description":"Managed-model access level, e.g. none/flash/pro."},"membership_id":{"type":["string","null"]},"membership_role":{"type":["string","null"]},"membership_status":{"type":["string","null"]},"directory_revision":{"type":["string","null"]},"billing_portal_url":{"type":"string"},"credits_remaining":{"type":["integer","null"]},"current_tier":{"type":["string","null"]},"quota_contract":{"type":["integer","null"]},"budget_messages":{"type":["integer","null"]},"budget_tokens_flash":{"type":["integer","null"]},"budget_tokens_pro":{"type":["integer","null"]},"subscription_usage_url":{"type":["string","null"]}},"description":"Desktop license validation response (v3-compatible field superset)."},"LicenseConsumeRequest":{"type":"object","required":["units","reason"],"additionalProperties":false,"properties":{"units":{"type":"integer","minimum":1,"description":"Budget units to consume."},"reason":{"type":"string","minLength":1,"maxLength":255},"metadata":{"type":"object","additionalProperties":true,"description":"Optional consumption metadata."}}},"LicenseConsumeResponse":{"type":"object","additionalProperties":true,"properties":{"credits_remaining":{"type":"integer"},"remaining":{"type":["integer","null"]}}},"AuthExchangeRequest":{"type":"object","required":["code"],"additionalProperties":false,"properties":{"code":{"type":"string","minLength":1,"description":"Short-lived auth code from the Desktop sign-in flow."},"device_id":{"type":"string","maxLength":128},"client_id":{"type":"string","format":"uuid"},"platform":{"type":"string","maxLength":64},"app_version":{"type":"string","maxLength":64}}},"AuthRefreshRequest":{"type":"object","required":["refresh_token"],"additionalProperties":false,"properties":{"refresh_token":{"type":"string","description":"Refresh token issued by /api/desktop/auth/exchange."}}},"TokenSet":{"type":"object","additionalProperties":true,"properties":{"access_token":{"type":"string"},"refresh_token":{"type":"string"},"expires_in":{"type":"integer"}}},"TeamDirectoryV2":{"type":"object","additionalProperties":true,"properties":{"schema_version":{"type":"integer","const":2},"client_id":{"type":"string","format":"uuid"},"revision":{"type":"string"},"generated_at":{"type":"string","format":"date-time"},"valid_until":{"type":"string","format":"date-time"},"caller":{"type":"object","additionalProperties":true},"members":{"type":"array","items":{"type":"object","additionalProperties":true}},"lease":{"type":"object","additionalProperties":true,"properties":{"token":{"type":"string"},"expires_at":{"type":"string","format":"date-time"}}}}},"JwksDocument":{"type":"object","required":["keys"],"additionalProperties":true,"properties":{"keys":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"JSON Web Key (RFC 7517), e.g. an RSA public key with kty, kid, use, alg, n and e."}}},"description":"RFC 7517 JSON Web Key Set used to verify directory lease signatures."},"DownloadError":{"type":"object","additionalProperties":true,"required":["reason"],"properties":{"reason":{"type":"string","description":"Stable machine-readable download failure code."},"plan":{"type":["string","null"],"description":"Plan identifier, present on 402 responses."}}},"RemoteProcessingRoutesResponse":{"type":"object","additionalProperties":true,"required":["routes"],"properties":{"routes":{"type":"array","items":{"$ref":"#/components/schemas/RemoteProcessingRoute"}}}},"RemoteProcessingRoute":{"type":"object","additionalProperties":true,"required":["route_id","data_categories","policy_ready","blockers","state","audit_verified","decision_revision"],"properties":{"route_id":{"type":"string","description":"Stable remote-processing route identifier."},"provider":{"type":["string","null"]},"purpose":{"type":["string","null"]},"data_categories":{"type":"array","items":{"type":"string"}},"credential_revision":{"type":["string","null"]},"policy_ready":{"type":"boolean"},"blockers":{"type":"array","items":{"type":"string"}},"state":{"type":"string","enum":["not_configured","approved","revoked","expired","stale"]},"audit_verified":{"type":"boolean"},"decision_revision":{"type":"integer"},"decision_by_membership_id":{"type":["string","null"]},"decision_by_access_level":{"type":["string","null"],"enum":["owner","admin",null]},"approved_at":{"type":["string","null"],"format":"date-time"},"expires_at":{"type":["string","null"],"format":"date-time"},"revoked_at":{"type":["string","null"],"format":"date-time"},"fallback_behavior":{"type":["string","null"],"enum":["block_operation","local_only",null]},"user_attestations":{"type":["object","null"],"additionalProperties":true},"policy_manifest_hash":{"type":["string","null"]},"evidence_registry_hash":{"type":["string","null"]}},"description":"Control-plane state of one managed-model remote-processing route."},"SupportReportInitRequest":{"type":"object","required":["occurrence_id","filename","size_bytes"],"additionalProperties":false,"properties":{"occurrence_id":{"type":"string","format":"uuid","description":"Unique occurrence id; idempotency key for the report."},"filename":{"type":"string","maxLength":255,"description":"Name of the report bundle file."},"size_bytes":{"type":"integer","minimum":1,"description":"Size of the report bundle in bytes."}}},"SupportReportInitResponse":{"type":"object","additionalProperties":true,"required":["already_filed"],"properties":{"already_filed":{"type":"boolean","description":"True when the occurrence already has an attached report; such bodies carry the existing ticket and no upload target."},"ticket":{"$ref":"#/components/schemas/SupportReportTicket"},"attached":{"type":"boolean"},"attachment_status":{"type":"string","enum":["attached"]},"repairing_ticket":{"$ref":"#/components/schemas/SupportReportTicket"},"upload":{"$ref":"#/components/schemas/SupportReportUploadTarget"},"asset_url":{"type":["string","null"],"format":"uri"}}},"SupportReportUploadTarget":{"type":"object","additionalProperties":true,"required":["url","headers","expires_in"],"properties":{"url":{"type":"string","format":"uri","description":"One-time upload URL for the report bundle."},"headers":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"key":{"type":"string"},"value":{"type":"string"}}},"description":"HTTP headers to send with the bundle PUT (e.g. content-type)."},"expires_in":{"type":"integer","description":"Seconds until the upload target expires."}}},"SupportReportTicket":{"type":"object","additionalProperties":true,"required":["id","identifier","url"],"properties":{"id":{"type":"string"},"identifier":{"type":"string","description":"Short human-facing ticket identifier (e.g. AGC-123)."},"url":{"type":"string","format":"uri"}}},"SupportReportCompleteRequest":{"type":"object","required":["occurrence_id","user_note"],"additionalProperties":false,"properties":{"occurrence_id":{"type":"string","format":"uuid","description":"Unique occurrence id; idempotency key for the report."},"conversation_id":{"type":["string","null"],"maxLength":200},"app_version":{"type":["string","null"],"maxLength":200},"platform":{"type":["string","null"],"maxLength":200},"os_version":{"type":["string","null"],"maxLength":200},"locale":{"type":["string","null"],"maxLength":200},"error_type":{"type":["string","null"],"maxLength":200},"error_code":{"type":["string","null"],"maxLength":200},"error_class":{"type":["string","null"],"maxLength":200},"report_summary":{"type":["string","null"],"maxLength":200},"report_surface":{"type":["string","null"],"enum":["chat_error","agent_offer","user_request"]},"impact":{"type":["string","null"],"enum":["blocked_workflow","degraded_workflow","incorrect_result","security_or_privacy","data_integrity","cosmetic","unknown"]},"reproducibility":{"type":["string","null"],"enum":["always","intermittent","once","unknown"]},"workaround":{"type":["string","null"],"enum":["none","available","unknown"]},"bundle_bytes":{"type":["integer","null"],"minimum":0},"bundle_file_count":{"type":["integer","null"],"minimum":0},"truncated_entries":{"type":["array","null"],"maxItems":50,"items":{"type":"string","maxLength":200}},"user_note":{"type":"string","minLength":1,"maxLength":4000,"description":"Human- or agent-written summary of the problem."},"filename":{"type":["string","null"],"maxLength":255},"asset_url":{"type":["string","null"],"format":"uri","description":"Public https URL of the uploaded bundle on Linear upload storage."}}},"SupportReportCompleteResponse":{"type":"object","additionalProperties":true,"required":["ticket","created","attached","attachment_status","retryable"],"properties":{"ticket":{"$ref":"#/components/schemas/SupportReportTicket"},"created":{"type":"boolean","description":"True when a new ticket was created; false when the existing ticket was reused."},"attached":{"type":"boolean","description":"True when the bundle is attached to the ticket."},"attachment_status":{"type":"string","enum":["attached","missing","unknown"]},"retryable":{"type":"boolean","description":"True when the ticket needs another attempt (bundle missing or unknown)."}}}}}}