{"openapi":"3.1.0","info":{"title":"Agente Public API","version":"2026-08-24","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.","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":{"type":"object","description":"RFC 7517 JWKS document."}}}}}}},"/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."},"401":{"description":"Unauthenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/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":{"type":"object","additionalProperties":true,"properties":{"routes":{"type":"array","items":{"type":"object","additionalProperties":true}}}}}}},"401":{"description":"Unauthenticated.","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":[]}],"responses":{"200":{"description":"Upload session initialized."},"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"}}}}}}},"/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":[]}],"responses":{"200":{"description":"Support report submitted."},"401":{"description":"Missing or invalid bearer token.","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"}}}}}}}}