{ "openapi": "3.1.0", "info": { "title": "AgentCost API", "description": "Track LLM costs in your AI applications.\n\nAgentCost records every LLM call with model, tokens, cost, latency and status, then reports spend by agent, workflow, project and model.\n\n**Public, no credentials required:** everything under `/v1/pricing` (the model catalogue and its per-1k rates) and `/v1/health`.\n\n**Everything else** needs either a project API key (`Authorization: Bearer sk_...`) or a session token plus a `project_id`.\n\nErrors return a structured envelope: `error.code`, `error.message`, `error.hint`.", "termsOfService": "https://agentcost.tech/terms", "contact": { "name": "AgentCost", "url": "https://agentcost.tech/contact", "email": "hello@agentcost.tech" }, "license": { "name": "MIT", "url": "https://github.com/agentcost-ai/agentcost-sdk/blob/main/LICENSE" }, "version": "0.1.3", "x-mirror": "https://agentcost.tech/api" }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." }, { "url": "https://agentcost.tech/api", "description": "Cached mirror on the website. Serves the public read endpoints and the cost estimator, and does not sleep." } ], "paths": { "/v1/auth/register": { "post": { "tags": [ "Authentication" ], "summary": "Register", "description": "Register a new user account.\n\n- **email**: Valid email address (must be unique)\n- **password**: Min 8 chars, must include uppercase, lowercase, and number\n- **name**: Optional display name\n- **accept_terms**: Must be true - explicit consent to Terms of Service\n- **accept_privacy**: Must be true - explicit consent to Privacy Policy\n- **terms_version**: Version of Terms being accepted (e.g., \"1.0\")\n- **privacy_version**: Version of Privacy Policy being accepted (e.g., \"1.0\")\n\nLegal consent is recorded with timestamp, IP address, and user agent for audit compliance.\n\nThe user is logged in immediately: the response includes the same token payload\nas /login, plus a default project (API key shown ONCE) and whether the\nverification email was actually sent.", "operationId": "authentication_register", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserRegister" } } }, "required": true }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterResponse" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/auth/google": { "post": { "tags": [ "Authentication" ], "summary": "Google Auth", "description": "Authenticate or register with Google.\n\nAccepts a Google ID token (credential) from Google Identity Services.\n- If the user exists, signs them in.\n- If the user doesn't exist, creates a new account and signs them in.\n\nGoogle users get auto-verified email and no password is required.", "operationId": "authentication_google_auth", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GoogleAuthRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenResponse" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/auth/github": { "post": { "tags": [ "Authentication" ], "summary": "Github Auth", "description": "Authenticate or register with GitHub.\n\nAccepts the authorization code from GitHub's OAuth redirect.\n- If the user exists, signs them in.\n- If the user doesn't exist, creates a new account and signs them in.\n\nGitHub users get auto-verified email and no password is required.", "operationId": "authentication_github_auth", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GitHubAuthRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenResponse" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/auth/policies/current": { "get": { "tags": [ "Authentication" ], "summary": "Get Current Policy Versions", "description": "Get current policy versions.\n\nUse this to display correct versions to users during signup\nand to check if policies have been updated.", "operationId": "authentication_get_current_policy_versions", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/auth/policies/status": { "get": { "tags": [ "Authentication" ], "summary": "Check Policy Status", "description": "Check if current user has accepted the latest policy versions.\n\nReturns status for both Terms of Service and Privacy Policy,\nincluding whether re-acceptance is required.", "operationId": "authentication_check_policy_status", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyCheckResponse" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "HTTPBearer": [] } ] }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/auth/policies/accept": { "post": { "tags": [ "Authentication" ], "summary": "Accept Policies", "description": "Accept updated policy versions.\n\nUse this when policies have been updated and user needs to re-accept.\nRecords consent with timestamp, IP, and user agent for audit trail.", "operationId": "authentication_accept_policies", "requestBody": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/PolicyConsentInput" }, "type": "array", "title": "Consents" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyCheckResponse" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "HTTPBearer": [] } ] }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/auth/login": { "post": { "tags": [ "Authentication" ], "summary": "Login", "description": "Authenticate user and get access token.\n\n- **email**: User's email address\n- **password**: User's password\n- **remember_me**: If true, session lasts 30 days instead of 7", "operationId": "authentication_login", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserLogin" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenResponse" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/auth/refresh": { "post": { "tags": [ "Authentication" ], "summary": "Refresh Token", "description": "Get a new access token using a refresh token.\n\nUse this when your access token expires.", "operationId": "authentication_refresh_token", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefreshTokenRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenResponse" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/auth/logout": { "post": { "tags": [ "Authentication" ], "summary": "Logout", "description": "Logout and invalidate current session.", "operationId": "authentication_logout", "responses": { "204": { "description": "Successful Response" }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "HTTPBearer": [] } ] }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/auth/logout-all": { "post": { "tags": [ "Authentication" ], "summary": "Logout All", "description": "Logout from all devices and invalidate all sessions.\n\nRequires authentication.", "operationId": "authentication_logout_all", "responses": { "204": { "description": "Successful Response" }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "HTTPBearer": [] } ] }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/auth/me": { "get": { "tags": [ "Authentication" ], "summary": "Get Me", "description": "Get current authenticated user's profile.\n\nRequires authentication.\nAlso updates last_active_at to track user activity (debounced to 5 mins).", "operationId": "authentication_get_me", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserResponse" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "HTTPBearer": [] } ] }, "patch": { "tags": [ "Authentication" ], "summary": "Update Me", "description": "Update current user's profile.\n\nRequires authentication.", "operationId": "authentication_update_me", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileUpdate" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserResponse" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "HTTPBearer": [] } ] }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/auth/password/change": { "post": { "tags": [ "Authentication" ], "summary": "Change Password", "description": "Change password for current user.\n\nRequires authentication and current password.", "operationId": "authentication_change_password", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasswordChangeRequest" } } }, "required": true }, "responses": { "204": { "description": "Successful Response" }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "HTTPBearer": [] } ] }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/auth/password/reset-request": { "post": { "tags": [ "Authentication" ], "summary": "Request Password Reset", "description": "Request a password reset email.\n\nFor security, always returns 204 even if email doesn't exist.\nRate limited to 3 requests per email per hour.", "operationId": "authentication_request_password_reset", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasswordResetRequest" } } }, "required": true }, "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/auth/password/reset": { "post": { "tags": [ "Authentication" ], "summary": "Reset Password", "description": "Reset password using token from email.", "operationId": "authentication_reset_password", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasswordResetConfirm" } } }, "required": true }, "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/auth/verify-email": { "post": { "tags": [ "Authentication" ], "summary": "Verify Email", "description": "Verify email address using token from email.", "operationId": "authentication_verify_email", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailVerificationRequest" } } }, "required": true }, "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/auth/resend-verification": { "post": { "tags": [ "Authentication" ], "summary": "Resend Verification", "description": "Resend email verification link.\n\nFor security, always returns 204 even if email doesn't exist.", "operationId": "authentication_resend_verification", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResendVerificationRequest" } } }, "required": true }, "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/auth/sessions": { "get": { "tags": [ "Authentication" ], "summary": "List Sessions", "description": "List all active sessions for current user.\n\nRequires authentication.", "operationId": "authentication_list_sessions", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionListResponse" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "HTTPBearer": [] } ] }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/auth/sessions/{session_id}": { "delete": { "tags": [ "Authentication" ], "summary": "Revoke Session", "description": "Revoke a specific session.\n\nRequires authentication.", "operationId": "authentication_revoke_session", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } } ], "responses": { "204": { "description": "Successful Response" }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/projects/{project_id}/members": { "get": { "tags": [ "Project Members" ], "summary": "List Members", "description": "List all members of a project.\n\nRequires VIEW_MEMBERS permission (all roles have this).", "operationId": "project_members_list_members", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Project Id" } }, { "name": "include_pending", "in": "query", "required": false, "schema": { "type": "boolean", "default": true, "title": "Include Pending" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MembersListResponse" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "post": { "tags": [ "Project Members" ], "summary": "Invite Member", "description": "Invite a user to the project.\n\nRequires INVITE_MEMBERS permission (admin only).\nIf the user has an account, they'll receive an invitation to accept.\nIf the user doesn't have an account, they'll receive an email with instructions to register.", "operationId": "project_members_invite_member", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Project Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteMemberRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/projects/{project_id}/members/{user_id}": { "patch": { "tags": [ "Project Members" ], "summary": "Update Member Role", "description": "Update a member's role.\n\nRequires CHANGE_ROLES permission (admin only).\nOnly project owners can promote to admin.", "operationId": "project_members_update_member_role", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Project Id" } }, { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string", "title": "User Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateRoleRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "delete": { "tags": [ "Project Members" ], "summary": "Remove Member", "description": "Remove a member from the project.\n\nRequires REMOVE_MEMBERS permission (admin only).\nAdmins cannot remove other admins (only the owner can).", "operationId": "project_members_remove_member", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Project Id" } }, { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string", "title": "User Id" } } ], "responses": { "204": { "description": "Successful Response" }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/projects/{project_id}/leave": { "post": { "tags": [ "Project Members" ], "summary": "Leave Project", "description": "Leave a project voluntarily.\n\nProject owners cannot leave - they must transfer ownership or delete the project.", "operationId": "project_members_leave_project", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Project Id" } } ], "responses": { "204": { "description": "Successful Response" }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/projects/invitations/pending": { "get": { "tags": [ "Project Members" ], "summary": "Get Pending Invitations", "description": "Get all pending project invitations for the current user.", "operationId": "project_members_get_pending_invitations", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvitationsListResponse" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "HTTPBearer": [] } ] }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/projects/{project_id}/invitations/accept": { "post": { "tags": [ "Project Members" ], "summary": "Accept Invitation", "description": "Accept a project invitation.", "operationId": "project_members_accept_invitation", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Project Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/projects/{project_id}/invitations/decline": { "post": { "tags": [ "Project Members" ], "summary": "Decline Invitation", "description": "Decline a project invitation.", "operationId": "project_members_decline_invitation", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Project Id" } } ], "responses": { "204": { "description": "Successful Response" }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/events/batch": { "post": { "tags": [ "Events" ], "summary": "Ingest Events Batch", "description": "Ingest a batch of events.\n\nThis is the main endpoint called by the AgentCost SDK.\nEvents are stored and processed for analytics.\n\nMalformed events are dropped individually and reported back; the batch as\na whole still succeeds so the SDK does not retry a payload it can never\nget accepted.", "operationId": "events_ingest_events_batch", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventBatchRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventBatchResponse" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "APIKeyHeader": [] } ] }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/events": { "get": { "tags": [ "Events" ], "summary": "List Events", "description": "List events for a project.\n\nSupports filtering by agent_name and model.", "operationId": "events_list_events", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "default": 100, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Offset" } }, { "name": "agent_name", "in": "query", "required": false, "schema": { "type": "string", "title": "Agent Name" } }, { "name": "model", "in": "query", "required": false, "schema": { "type": "string", "title": "Model" } }, { "name": "project_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Project ID. Required for JWT-authenticated requests; ignored for SDK API-key requests (the project is derived from the key).", "title": "Project Id" }, "description": "Project ID. Required for JWT-authenticated requests; ignored for SDK API-key requests (the project is derived from the key)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/EventResponse" }, "title": "Response List Events V1 Events Get" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/events/count": { "get": { "tags": [ "Events" ], "summary": "Get Event Count", "description": "Get total event count for project.", "operationId": "events_get_event_count", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "project_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Project ID. Required for JWT-authenticated requests; ignored for SDK API-key requests (the project is derived from the key).", "title": "Project Id" }, "description": "Project ID. Required for JWT-authenticated requests; ignored for SDK API-key requests (the project is derived from the key)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/analytics/overview": { "get": { "tags": [ "Analytics" ], "summary": "Get Overview", "description": "Get overview metrics for the project.\n\nReturns total cost, calls, tokens, and averages.", "operationId": "analytics_get_overview", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "range", "in": "query", "required": false, "schema": { "enum": [ "1h", "24h", "7d", "30d", "90d" ], "type": "string", "description": "Time range: 1h, 24h, 7d, 30d, 90d", "default": "7d", "title": "Range" }, "description": "Time range: 1h, 24h, 7d, 30d, 90d" }, { "name": "project_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Project ID. Required for JWT-authenticated requests; ignored for SDK API-key requests (the project is derived from the key).", "title": "Project Id" }, "description": "Project ID. Required for JWT-authenticated requests; ignored for SDK API-key requests (the project is derived from the key)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsOverview" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/analytics/agents": { "get": { "tags": [ "Analytics" ], "summary": "Get Agent Stats", "description": "Get per-agent statistics.\n\nReturns cost, calls, and performance metrics per agent.", "operationId": "analytics_get_agent_stats", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "range", "in": "query", "required": false, "schema": { "enum": [ "1h", "24h", "7d", "30d", "90d" ], "type": "string", "description": "Time range: 1h, 24h, 7d, 30d, 90d", "default": "7d", "title": "Range" }, "description": "Time range: 1h, 24h, 7d, 30d, 90d" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 10, "title": "Limit" } }, { "name": "project_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Project ID. Required for JWT-authenticated requests; ignored for SDK API-key requests (the project is derived from the key).", "title": "Project Id" }, "description": "Project ID. Required for JWT-authenticated requests; ignored for SDK API-key requests (the project is derived from the key)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AgentStats" }, "title": "Response Get Agent Stats V1 Analytics Agents Get" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/analytics/by/{dimension}": { "get": { "tags": [ "Analytics" ], "summary": "Get Dimension Stats", "description": "Cost and volume grouped by one dimension.\n\n`user` and `session` are read from the `user_id` and `session_id` keys in\nevent metadata, promoted to indexed columns at ingest. Tag calls with\n`track_costs.metadata(user_id=...)` to populate them — this is what answers\n\"what is each developer costing us\".\n\nEvents with no value for the requested dimension are excluded, not grouped\nunder a placeholder.", "operationId": "analytics_get_dimension_stats", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "dimension", "in": "path", "required": true, "schema": { "enum": [ "user", "session", "workflow", "tool", "model", "agent" ], "type": "string", "title": "Dimension" } }, { "name": "range", "in": "query", "required": false, "schema": { "enum": [ "1h", "24h", "7d", "30d", "90d" ], "type": "string", "description": "Time range: 1h, 24h, 7d, 30d, 90d", "default": "7d", "title": "Range" }, "description": "Time range: 1h, 24h, 7d, 30d, 90d" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 500, "minimum": 1, "default": 50, "title": "Limit" } }, { "name": "project_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Project ID. Required for JWT-authenticated requests; ignored for SDK API-key requests (the project is derived from the key).", "title": "Project Id" }, "description": "Project ID. Required for JWT-authenticated requests; ignored for SDK API-key requests (the project is derived from the key)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DimensionStat" }, "title": "Response Get Dimension Stats V1 Analytics By Dimension Get" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/analytics/cache": { "get": { "tags": [ "Analytics" ], "summary": "Get Cache Analytics", "description": "Prompt-cache hit rate and what caching earned this window, in USD.\n\nSavings are measured against billing every cached token at the full input\nrate. A model with no published cache rate contributes zero, exactly as\ningest prices it.", "operationId": "analytics_get_cache_analytics", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "range", "in": "query", "required": false, "schema": { "enum": [ "1h", "24h", "7d", "30d", "90d" ], "type": "string", "description": "Time range: 1h, 24h, 7d, 30d, 90d", "default": "7d", "title": "Range" }, "description": "Time range: 1h, 24h, 7d, 30d, 90d" }, { "name": "project_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Project ID. Required for JWT-authenticated requests; ignored for SDK API-key requests (the project is derived from the key).", "title": "Project Id" }, "description": "Project ID. Required for JWT-authenticated requests; ignored for SDK API-key requests (the project is derived from the key)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CacheAnalytics" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/analytics/models": { "get": { "tags": [ "Analytics" ], "summary": "Get Model Stats", "description": "Get per-model statistics.\n\nReturns cost, calls, and performance metrics per model.", "operationId": "analytics_get_model_stats", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "range", "in": "query", "required": false, "schema": { "enum": [ "1h", "24h", "7d", "30d", "90d" ], "type": "string", "description": "Time range: 1h, 24h, 7d, 30d, 90d", "default": "7d", "title": "Range" }, "description": "Time range: 1h, 24h, 7d, 30d, 90d" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 10, "title": "Limit" } }, { "name": "project_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Project ID. Required for JWT-authenticated requests; ignored for SDK API-key requests (the project is derived from the key).", "title": "Project Id" }, "description": "Project ID. Required for JWT-authenticated requests; ignored for SDK API-key requests (the project is derived from the key)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ModelStats" }, "title": "Response Get Model Stats V1 Analytics Models Get" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/analytics/timeseries": { "get": { "tags": [ "Analytics" ], "summary": "Get Timeseries", "description": "Get time series data.\n\nReturns cost, calls, and tokens over time.", "operationId": "analytics_get_timeseries", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "range", "in": "query", "required": false, "schema": { "enum": [ "1h", "24h", "7d", "30d", "90d" ], "type": "string", "description": "Time range: 1h, 24h, 7d, 30d, 90d", "default": "7d", "title": "Range" }, "description": "Time range: 1h, 24h, 7d, 30d, 90d" }, { "name": "granularity", "in": "query", "required": false, "schema": { "enum": [ "hour", "day" ], "type": "string", "description": "Granularity: hour, day", "default": "day", "title": "Granularity" }, "description": "Granularity: hour, day" }, { "name": "project_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Project ID. Required for JWT-authenticated requests; ignored for SDK API-key requests (the project is derived from the key).", "title": "Project Id" }, "description": "Project ID. Required for JWT-authenticated requests; ignored for SDK API-key requests (the project is derived from the key)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TimeSeriesPoint" }, "title": "Response Get Timeseries V1 Analytics Timeseries Get" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/analytics/report": { "get": { "tags": [ "Analytics" ], "summary": "Get Executive Report", "description": "Build the Executive Cost & Usage Report.\n\nOne composite payload: executive summary (KPIs + period-over-period deltas)\nplus deep breakdowns — latency percentiles, cost concentration / Pareto,\ntoken efficiency, error analysis, usage cadence, run-rate projection,\nbudget status, and an optimization-savings rollup.\n\nSupports preset ranges, ``mtd`` (month-to-date), and a custom\n``start``/``end`` window. Deltas compare against the immediately preceding\nwindow of equal length.", "operationId": "analytics_get_executive_report", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "range", "in": "query", "required": false, "schema": { "enum": [ "1h", "24h", "7d", "30d", "90d", "mtd" ], "type": "string", "description": "Preset window. Ignored when start+end are both provided.", "default": "30d", "title": "Range" }, "description": "Preset window. Ignored when start+end are both provided." }, { "name": "start", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Custom window start (ISO 8601). Requires end.", "title": "Start" }, "description": "Custom window start (ISO 8601). Requires end." }, { "name": "end", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Custom window end (ISO 8601). Requires start.", "title": "End" }, "description": "Custom window end (ISO 8601). Requires start." }, { "name": "top_n", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 50, "minimum": 3, "description": "Rows for model/agent breakdown tables.", "default": 10, "title": "Top N" }, "description": "Rows for model/agent breakdown tables." }, { "name": "project_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Project ID. Required for JWT-authenticated requests; ignored for SDK API-key requests (the project is derived from the key).", "title": "Project Id" }, "description": "Project ID. Required for JWT-authenticated requests; ignored for SDK API-key requests (the project is derived from the key)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecutiveReport" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/analytics/full": { "get": { "tags": [ "Analytics" ], "summary": "Get Full Analytics", "description": "Get complete analytics response.\n\nIncludes overview, agent stats, model stats, and time series.", "operationId": "analytics_get_full_analytics", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 90, "minimum": 1, "default": 7, "title": "Days" } }, { "name": "project_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Project ID. Required for JWT-authenticated requests; ignored for SDK API-key requests (the project is derived from the key).", "title": "Project Id" }, "description": "Project ID. Required for JWT-authenticated requests; ignored for SDK API-key requests (the project is derived from the key)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsResponse" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/analytics/workflows": { "get": { "tags": [ "Analytics" ], "summary": "Get Workflow Stats", "description": "Cost per workflow, including the average cost of a single run.", "operationId": "analytics_get_workflow_stats", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "range", "in": "query", "required": false, "schema": { "enum": [ "1h", "24h", "7d", "30d", "90d" ], "type": "string", "default": "7d", "title": "Range" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 20, "title": "Limit" } }, { "name": "project_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Project ID. Required for JWT-authenticated requests; ignored for SDK API-key requests (the project is derived from the key).", "title": "Project Id" }, "description": "Project ID. Required for JWT-authenticated requests; ignored for SDK API-key requests (the project is derived from the key)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/analytics/workflows/steps": { "get": { "tags": [ "Analytics" ], "summary": "Get Step Stats", "description": "Cost per step. calls_per_run above 1 indicates retries or a loop.", "operationId": "analytics_get_step_stats", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "range", "in": "query", "required": false, "schema": { "enum": [ "1h", "24h", "7d", "30d", "90d" ], "type": "string", "default": "7d", "title": "Range" } }, { "name": "workflow", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Restrict to one workflow", "title": "Workflow" }, "description": "Restrict to one workflow" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Limit" } }, { "name": "project_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Project ID. Required for JWT-authenticated requests; ignored for SDK API-key requests (the project is derived from the key).", "title": "Project Id" }, "description": "Project ID. Required for JWT-authenticated requests; ignored for SDK API-key requests (the project is derived from the key)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/analytics/workflows/tools": { "get": { "tags": [ "Analytics" ], "summary": "Get Tool Stats", "description": "LLM spend incurred underneath each named tool.", "operationId": "analytics_get_tool_stats", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "range", "in": "query", "required": false, "schema": { "enum": [ "1h", "24h", "7d", "30d", "90d" ], "type": "string", "default": "7d", "title": "Range" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Limit" } }, { "name": "project_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Project ID. Required for JWT-authenticated requests; ignored for SDK API-key requests (the project is derived from the key).", "title": "Project Id" }, "description": "Project ID. Required for JWT-authenticated requests; ignored for SDK API-key requests (the project is derived from the key)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/analytics/workflows/repeated-work": { "get": { "tags": [ "Analytics" ], "summary": "Get Repeated Work", "description": "Identical calls repeated within a single run, and what they cost.", "operationId": "analytics_get_repeated_work", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "range", "in": "query", "required": false, "schema": { "enum": [ "1h", "24h", "7d", "30d", "90d" ], "type": "string", "default": "7d", "title": "Range" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 25, "title": "Limit" } }, { "name": "project_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Project ID. Required for JWT-authenticated requests; ignored for SDK API-key requests (the project is derived from the key).", "title": "Project Id" }, "description": "Project ID. Required for JWT-authenticated requests; ignored for SDK API-key requests (the project is derived from the key)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/analytics/workflows/outcomes": { "get": { "tags": [ "Analytics" ], "summary": "Get Outcome Stats", "description": "Cost per completed outcome. Requires track_costs.outcome() in the run.", "operationId": "analytics_get_outcome_stats", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "range", "in": "query", "required": false, "schema": { "enum": [ "1h", "24h", "7d", "30d", "90d" ], "type": "string", "default": "7d", "title": "Range" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 20, "title": "Limit" } }, { "name": "project_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Project ID. Required for JWT-authenticated requests; ignored for SDK API-key requests (the project is derived from the key).", "title": "Project Id" }, "description": "Project ID. Required for JWT-authenticated requests; ignored for SDK API-key requests (the project is derived from the key)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/analytics/workflows/distribution": { "get": { "tags": [ "Analytics" ], "summary": "Get Run Cost Distribution", "description": "Distribution of cost per run, with percentiles and the tail's share of spend.\n\nComputed over every run in the window rather than a top-N slice, because a\ndistribution drawn from the most expensive runs is not a distribution.", "operationId": "analytics_get_run_cost_distribution", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "range", "in": "query", "required": false, "schema": { "enum": [ "1h", "24h", "7d", "30d", "90d" ], "type": "string", "default": "7d", "title": "Range" } }, { "name": "workflow", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Defaults to the highest-spend workflow", "title": "Workflow" }, "description": "Defaults to the highest-spend workflow" }, { "name": "buckets", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 60, "minimum": 6, "default": 24, "title": "Buckets" } }, { "name": "project_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Project ID. Required for JWT-authenticated requests; ignored for SDK API-key requests (the project is derived from the key).", "title": "Project Id" }, "description": "Project ID. Required for JWT-authenticated requests; ignored for SDK API-key requests (the project is derived from the key)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/analytics/traces": { "get": { "tags": [ "Analytics" ], "summary": "List Traces", "description": "Individual runs, most expensive first.", "operationId": "analytics_list_traces", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "range", "in": "query", "required": false, "schema": { "enum": [ "1h", "24h", "7d", "30d", "90d" ], "type": "string", "default": "7d", "title": "Range" } }, { "name": "workflow", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Workflow" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Limit" } }, { "name": "project_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Project ID. Required for JWT-authenticated requests; ignored for SDK API-key requests (the project is derived from the key).", "title": "Project Id" }, "description": "Project ID. Required for JWT-authenticated requests; ignored for SDK API-key requests (the project is derived from the key)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/analytics/traces/{trace_id}": { "get": { "tags": [ "Analytics" ], "summary": "Get Trace Detail", "description": "Every span of one run, ordered as it executed.", "operationId": "analytics_get_trace_detail", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "trace_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Trace Id" } }, { "name": "project_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Project ID. Required for JWT-authenticated requests; ignored for SDK API-key requests (the project is derived from the key).", "title": "Project Id" }, "description": "Project ID. Required for JWT-authenticated requests; ignored for SDK API-key requests (the project is derived from the key)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/projects": { "get": { "tags": [ "Projects" ], "summary": "List My Projects", "description": "List every project the authenticated user can access, including projects\nthey own and projects they were invited to (pending and accepted).\n\nUsed by the dashboard's project switcher so invited members can find and\nopen the projects they have access to without ever needing the project's\nraw API key.", "operationId": "projects_list_my_projects", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Response List My Projects V1 Projects Get" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "HTTPBearer": [] } ] }, "post": { "tags": [ "Projects" ], "summary": "Create Project", "description": "Create a new project.\n\nRequires authentication. The project will be linked to the authenticated user.\n\nReturns the project with its API key.\n\nIMPORTANT: Store the API key securely - it will NEVER be shown again!\nThe API key is hashed before storage for security.", "operationId": "projects_create_project", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectCreate" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "HTTPBearer": [] } ] }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/projects/me": { "get": { "tags": [ "Projects" ], "summary": "Get Current Project", "description": "Get the current project (based on API key).\n\nNote: API key is not returned for security reasons.", "operationId": "projects_get_current_project", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "APIKeyHeader": [] } ] }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/projects/{project_id}": { "get": { "tags": [ "Projects" ], "summary": "Get Project", "description": "Get project by ID.\n\nDual-auth: accepts either an SDK API key (returned project must match\n``project_id``) or a JWT + ``project_id`` query param that the caller\nhas VIEW_PROJECT permission on.", "operationId": "projects_get_project", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Project Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectResponse" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "patch": { "tags": [ "Projects" ], "summary": "Update Project", "description": "Update project settings.\n\nRequires JWT authentication and admin/owner role on the project.", "operationId": "projects_update_project", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Project Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectUpdate" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectResponse" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "delete": { "tags": [ "Projects" ], "summary": "Delete Project", "description": "Delete a project.\n\nRequires JWT authentication and admin/owner role on the project.\nWARNING: This will delete all associated events!", "operationId": "projects_delete_project", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Project Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/projects/{project_id}/budget": { "get": { "tags": [ "Projects" ], "summary": "Get Project Budget", "description": "Get budget settings and current month utilization for a project.", "operationId": "projects_get_project_budget", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Project Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectBudgetResponse" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "put": { "tags": [ "Projects" ], "summary": "Update Project Budget", "description": "Update project budget guardrail settings.", "operationId": "projects_update_project_budget", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Project Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectBudgetUpdate" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectBudgetResponse" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/projects/{project_id}/webhook": { "get": { "tags": [ "Projects" ], "summary": "Get Project Webhook", "description": "Current webhook configuration. The secret is never returned.", "operationId": "projects_get_project_webhook", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Project Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectWebhookResponse" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "put": { "tags": [ "Projects" ], "summary": "Update Project Webhook", "description": "Configure signed push egress for budget threshold crossings.\n\nRequires project-edit permission, not merely view: a webhook URL is an\nexfiltration path for spend data.\n\nSend `{\"url\": null}` to disable (this also clears the stored secret).\nWhen `url` is set, omitting `secret` keeps the existing one and an empty\nstring clears it; a `secret` without a `url` is rejected.", "operationId": "projects_update_project_webhook", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Project Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectWebhookUpdate" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectWebhookResponse" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/projects/{project_id}/webhook/test": { "post": { "tags": [ "Projects" ], "summary": "Test Project Webhook", "description": "Send a signed sample payload to the configured webhook, synchronously.\n\nLets an integration be verified at configuration time instead of at the\nfirst real budget crossing. The payload shape and signature scheme match\nlive deliveries; only the event type (`webhook.test`) differs.", "operationId": "projects_test_project_webhook", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Project Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectWebhookTestResponse" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/projects/{project_id}/budget-state": { "get": { "tags": [ "Projects" ], "summary": "Get Project Budget State", "description": "Compact budget position for machine consumers.\n\nAuthenticated with the **project API key**, not a user session, so an\nenforcement point can poll it with the same credential it uses to send\nevents.\n\nIntended use is polling — every 15–60s — and holding the result as cached\nstate. Do not call this inside a latency-sensitive decision path; `as_of`\nis returned so a consumer can reason about how stale its copy is.\n\nRead-only: unlike the ingest path, this never records threshold alerts and\nnever counts an in-flight cost.", "operationId": "projects_get_project_budget_state", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Project Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectBudgetState" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/projects/{project_id}/api-key/rotate": { "post": { "tags": [ "Projects" ], "summary": "Rotate Api Key", "description": "Rotate the project's API key.\n\nReturns the new API key ONCE. Requires regenerate_api_key permission.", "operationId": "projects_rotate_api_key", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Project Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/optimizations": { "get": { "tags": [ "Optimizations" ], "summary": "Get Optimizations", "description": "Get cost optimization suggestions for your project.\n\nAnalyzes usage patterns and suggests ways to reduce costs:\n- Model downgrades based on actual usage and dynamic pricing\n- Caching opportunities from detected input patterns\n- Anomaly alerts from statistical baseline deviations\n- Error pattern fixes with calculated wasted spend\n\nAll suggestions use real pricing data and statistical analysis.", "operationId": "optimizations_get_optimizations", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 90, "minimum": 1, "description": "Days of history to analyze", "default": 30, "title": "Days" }, "description": "Days of history to analyze" }, { "name": "include_low_priority", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Include low priority suggestions", "default": true, "title": "Include Low Priority" }, "description": "Include low priority suggestions" }, { "name": "project_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Project ID. Required for JWT-authenticated requests; ignored for SDK API-key requests (the project is derived from the key).", "title": "Project Id" }, "description": "Project ID. Required for JWT-authenticated requests; ignored for SDK API-key requests (the project is derived from the key)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "title": "Response Get Optimizations V1 Optimizations Get" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/optimizations/recommendations/generate": { "post": { "tags": [ "Optimizations" ], "summary": "Generate Recommendations", "description": "Generate optimization suggestions and persist top recommendations.\n\nThis endpoint intentionally has side effects and should be called\nexplicitly by clients when they want new recommendations recorded.", "operationId": "optimizations_generate_recommendations", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 90, "minimum": 1, "description": "Days of history to analyze", "default": 30, "title": "Days" }, "description": "Days of history to analyze" }, { "name": "include_low_priority", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Include low priority suggestions", "default": true, "title": "Include Low Priority" }, "description": "Include low priority suggestions" }, { "name": "project_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Project ID. Required for JWT-authenticated requests; ignored for SDK API-key requests (the project is derived from the key).", "title": "Project Id" }, "description": "Project ID. Required for JWT-authenticated requests; ignored for SDK API-key requests (the project is derived from the key)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "title": "Response Generate Recommendations V1 Optimizations Recommendations Generate Post" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/optimizations/summary": { "get": { "tags": [ "Optimizations" ], "summary": "Get Optimization Summary", "description": "Get optimization summary with total potential savings.\n\nReturns:\n- Total potential monthly savings and percentage\n- Current monthly spend for context\n- Suggestion count and breakdown by type\n- Recommendation effectiveness metrics\n- Top 5 recommendations", "operationId": "optimizations_get_optimization_summary", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 90, "minimum": 1, "description": "Days of history to analyze", "default": 30, "title": "Days" }, "description": "Days of history to analyze" }, { "name": "project_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Project ID. Required for JWT-authenticated requests; ignored for SDK API-key requests (the project is derived from the key).", "title": "Project Id" }, "description": "Project ID. Required for JWT-authenticated requests; ignored for SDK API-key requests (the project is derived from the key)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/optimizations/baselines/refresh": { "post": { "tags": [ "Optimizations" ], "summary": "Refresh Baselines", "description": "Refresh statistical baselines for the project.\n\nBaselines are used for anomaly detection and threshold calculations.\nThey should be recalculated periodically (e.g., weekly) or after\nsignificant changes to your agent configurations.", "operationId": "optimizations_refresh_baselines", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 90, "minimum": 7, "description": "Days of history for baseline calculation", "default": 30, "title": "Days" }, "description": "Days of history for baseline calculation" }, { "name": "project_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Project ID. Required for JWT-authenticated requests; ignored for SDK API-key requests (the project is derived from the key).", "title": "Project Id" }, "description": "Project ID. Required for JWT-authenticated requests; ignored for SDK API-key requests (the project is derived from the key)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/optimizations/baselines": { "get": { "tags": [ "Optimizations" ], "summary": "Get Baselines", "description": "Get current statistical baselines for the project.\n\nBaselines include mean and standard deviation for:\n- Cost per call\n- Token usage (input and output)\n- Latency\n- Daily call volume\n- Error rate", "operationId": "optimizations_get_baselines", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "agent_name", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by agent name", "title": "Agent Name" }, "description": "Filter by agent name" }, { "name": "model", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by model", "title": "Model" }, "description": "Filter by model" }, { "name": "project_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Project ID. Required for JWT-authenticated requests; ignored for SDK API-key requests (the project is derived from the key).", "title": "Project Id" }, "description": "Project ID. Required for JWT-authenticated requests; ignored for SDK API-key requests (the project is derived from the key)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/optimizations/caching-opportunities": { "get": { "tags": [ "Optimizations" ], "summary": "Get Caching Opportunities", "description": "Get detailed caching opportunity analysis.\n\nReturns agents with detected duplicate input patterns and\ncalculated potential savings from implementing caching.", "operationId": "optimizations_get_caching_opportunities", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "min_occurrences", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 2, "description": "Minimum duplicate occurrences", "default": 5, "title": "Min Occurrences" }, "description": "Minimum duplicate occurrences" }, { "name": "project_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Project ID. Required for JWT-authenticated requests; ignored for SDK API-key requests (the project is derived from the key).", "title": "Project Id" }, "description": "Project ID. Required for JWT-authenticated requests; ignored for SDK API-key requests (the project is derived from the key)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/optimizations/recommendations": { "get": { "tags": [ "Optimizations" ], "summary": "Get Pending Recommendations", "description": "Get pending optimization recommendations.\n\nThese are recommendations that have been generated but not yet\nimplemented or dismissed.", "operationId": "optimizations_get_pending_recommendations", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "project_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Project ID. Required for JWT-authenticated requests; ignored for SDK API-key requests (the project is derived from the key).", "title": "Project Id" }, "description": "Project ID. Required for JWT-authenticated requests; ignored for SDK API-key requests (the project is derived from the key)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/optimizations/recommendations/{recommendation_id}/implement": { "post": { "tags": [ "Optimizations" ], "summary": "Mark Recommendation Implemented", "description": "Mark a recommendation as implemented.\n\nThis helps track which recommendations users adopt and measure\ntheir actual effectiveness over time.", "operationId": "optimizations_mark_recommendation_implemented", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "recommendation_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Recommendation Id" } }, { "name": "project_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Project ID. Required for JWT-authenticated requests; ignored for SDK API-key requests (the project is derived from the key).", "title": "Project Id" }, "description": "Project ID. Required for JWT-authenticated requests; ignored for SDK API-key requests (the project is derived from the key)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/optimizations/recommendations/{recommendation_id}/dismiss": { "post": { "tags": [ "Optimizations" ], "summary": "Dismiss Recommendation", "description": "Dismiss a recommendation with optional feedback.\n\nFeedback helps improve future recommendations.", "operationId": "optimizations_dismiss_recommendation", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "recommendation_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Recommendation Id" } }, { "name": "project_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Project ID. Required for JWT-authenticated requests; ignored for SDK API-key requests (the project is derived from the key).", "title": "Project Id" }, "description": "Project ID. Required for JWT-authenticated requests; ignored for SDK API-key requests (the project is derived from the key)." } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecommendationFeedback" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/optimizations/recommendations/effectiveness": { "get": { "tags": [ "Optimizations" ], "summary": "Get Recommendation Effectiveness", "description": "Get effectiveness metrics for recommendations.\n\nShows how many recommendations were implemented, dismissed,\nand the accuracy of estimated vs actual savings.", "operationId": "optimizations_get_recommendation_effectiveness", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "project_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Project ID. Required for JWT-authenticated requests; ignored for SDK API-key requests (the project is derived from the key).", "title": "Project Id" }, "description": "Project ID. Required for JWT-authenticated requests; ignored for SDK API-key requests (the project is derived from the key)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/pricing/sync/status": { "get": { "tags": [ "Pricing" ], "summary": "Catalogue freshness", "description": "Get pricing sync status.", "operationId": "pricing_get_sync_status", "responses": { "200": { "description": "Catalogue size, freshness and composition.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PricingSyncStatusResponse" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/pricing": { "get": { "tags": [ "Pricing" ], "summary": "List model pricing", "description": "Get all model pricing. Public endpoint for SDKs.", "operationId": "pricing_get_all_pricing", "parameters": [ { "name": "provider", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Provider" } } ], "responses": { "200": { "description": "The full public catalogue, keyed by model name.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PricingCatalogResponse" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "post": { "tags": [ "Pricing" ], "summary": "Update Pricing", "description": "Update pricing for models (Admin).\n\nBounded and audited like the admin dashboard's per-model override: these\nrates are re-applied to every ingested event, so an unchecked value is\nwritten permanently into customers' cost history.", "operationId": "pricing_update_pricing", "security": [ { "HTTPBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/PricingEntry" }, "title": "Pricing Updates" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/pricing/deprecations": { "get": { "tags": [ "Pricing" ], "summary": "List announced model retirements", "description": "Active models with an upstream-announced retirement date, soonest first.\n\nPublic. The dates come from LiteLLM's deprecation_date and refresh with\nevery pricing sync. Registered before /{model_name} so the literal path\nwins over the catch-all.", "operationId": "pricing_list_deprecations", "responses": { "200": { "description": "Models with an announced retirement date, soonest first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeprecationsResponse" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/pricing/{model_name}": { "get": { "tags": [ "Pricing" ], "summary": "Get pricing for one model", "description": "Get pricing for a specific model.\n\nAnswers with the same resolver event ingestion bills with (exact then\ndeterministic fuzzy against the full catalogue). This route used to run its\nown substring match over the small DEFAULT_PRICING dict and could quote a\ndifferent price than the one events were actually costed at.", "operationId": "pricing_get_model_pricing", "parameters": [ { "name": "model_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Model Name" } } ], "responses": { "200": { "description": "Resolved rates. Unknown models resolve to zeros with source=fallback rather than 404.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelPricingResponse" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/pricing/sync/litellm": { "post": { "tags": [ "Pricing" ], "summary": "Sync From Litellm", "description": "Sync pricing from LiteLLM database.\n\nBy default, also regenerates model alternatives to reflect new pricing.", "operationId": "pricing_sync_from_litellm", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "track_changes", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Track Changes" } }, { "name": "auto_regenerate_alternatives", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Automatically regenerate model alternatives after sync", "default": true, "title": "Auto Regenerate Alternatives" }, "description": "Automatically regenerate model alternatives after sync" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/pricing/import": { "post": { "tags": [ "Pricing" ], "summary": "Import Pricing Bundle", "description": "Load a pricing catalogue from an uploaded bundle instead of the network.\n\nFor deployments that cannot reach GitHub — air-gapped, egress-restricted,\nor simply unwilling to depend on a third party being up at sync time. The\nbundle is LiteLLM's `model_prices_and_context_window.json` verbatim, so it\ncan be fetched on a connected machine, reviewed, and carried across.\n\nSame parsing, sanity bounds and change tracking as the network sync; only\nthe source of the JSON differs.", "operationId": "pricing_import_pricing_bundle", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "track_changes", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Track Changes" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Bundle" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/pricing/sync/openrouter": { "post": { "tags": [ "Pricing" ], "summary": "Sync From Openrouter", "description": "Sync pricing from OpenRouter API.\n\nBy default, also regenerates model alternatives to reflect new pricing.", "operationId": "pricing_sync_from_openrouter", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "auto_regenerate_alternatives", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Automatically regenerate model alternatives after sync", "default": true, "title": "Auto Regenerate Alternatives" }, "description": "Automatically regenerate model alternatives after sync" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/pricing/discover/{model_name}": { "get": { "tags": [ "Pricing" ], "summary": "Discover Alternatives", "description": "Find cheaper model alternatives based on pricing and capabilities.", "operationId": "pricing_discover_alternatives", "parameters": [ { "name": "model_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Model Name" } }, { "name": "avg_input_tokens", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Avg Input Tokens" } }, { "name": "avg_output_tokens", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Avg Output Tokens" } }, { "name": "requires_vision", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Requires Vision" } }, { "name": "requires_function_calling", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Requires Function Calling" } }, { "name": "same_provider_only", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Same Provider Only" } }, { "name": "max_results", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 50, "minimum": 1, "default": 10, "title": "Max Results" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/pricing/alternatives/generate": { "post": { "tags": [ "Pricing" ], "summary": "Generate Alternatives", "description": "Auto-generate model alternatives by analyzing pricing data.\n\nThis analyzes all 3500+ models in the pricing table and creates\nalternatives based on:\n- Same provider models (safer swaps)\n- Cross-provider models (for expensive models)\n- Capability matching (vision, function calling)\n- Price ratios and quality tier estimation\n\nRun this after syncing pricing data to populate the alternatives table.", "operationId": "pricing_generate_alternatives", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "max_alternatives_per_model", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 20, "minimum": 1, "default": 5, "title": "Max Alternatives Per Model" } }, { "name": "min_savings_percent", "in": "query", "required": false, "schema": { "type": "number", "maximum": 100, "minimum": 0, "default": 10, "title": "Min Savings Percent" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/pricing/alternatives/stats": { "get": { "tags": [ "Pricing" ], "summary": "Get Alternatives Stats", "description": "Get statistics about the model alternatives learning system.\n\nReturns:\n- Total alternatives in database\n- How many have learning feedback\n- Confidence distribution\n- Total estimated vs actual savings tracked", "operationId": "pricing_get_alternatives_stats", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/pricing/alternatives/{source_model}": { "get": { "tags": [ "Pricing" ], "summary": "Get Model Alternatives", "description": "Get learned alternatives for a specific model.\n\nReturns alternatives ranked by confidence score and value\n(confidence × savings potential).", "operationId": "pricing_get_model_alternatives", "parameters": [ { "name": "source_model", "in": "path", "required": true, "schema": { "type": "string", "title": "Source Model" } }, { "name": "min_confidence", "in": "query", "required": false, "schema": { "type": "number", "maximum": 1, "minimum": 0, "default": 0.3, "title": "Min Confidence" } }, { "name": "max_results", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 50, "minimum": 1, "default": 10, "title": "Max Results" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/feedback": { "post": { "tags": [ "Feedback" ], "summary": "Submit Feedback", "description": "Submit feedback or a request.\nAccepts authenticated and anonymous submissions.", "operationId": "feedback_submit_feedback", "security": [ { "HTTPBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedbackCreate" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedbackCreatedResponse" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "get": { "tags": [ "Feedback" ], "summary": "List Feedback", "description": "List feedback with filtering, search, and sorting.", "operationId": "feedback_list_feedback", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Type" } }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" } }, { "name": "priority", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Priority" } }, { "name": "sort_by", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(recent|popular|oldest)$", "default": "recent", "title": "Sort By" } }, { "name": "search", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Search" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 50, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Offset" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedbackListResponse" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/feedback/summary": { "get": { "tags": [ "Feedback" ], "summary": "Get Feedback Summary", "description": "Get summary counts for feedback.", "operationId": "feedback_get_feedback_summary", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedbackSummaryResponse" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "HTTPBearer": [] } ] }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/feedback/{feedback_id}": { "get": { "tags": [ "Feedback" ], "summary": "Get Feedback", "description": "Get a single feedback item.", "operationId": "feedback_get_feedback", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "feedback_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Feedback Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedbackResponse" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/feedback/{feedback_id}/upvote": { "post": { "tags": [ "Feedback" ], "summary": "Toggle Upvote", "description": "Toggle an upvote on a feedback item (requires authentication).", "operationId": "feedback_toggle_upvote", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "feedback_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Feedback Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/feedback/{feedback_id}/comments": { "post": { "tags": [ "Feedback" ], "summary": "Add Comment", "description": "Add a comment to feedback. Requires authentication (L4 fix).", "operationId": "feedback_add_comment", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "feedback_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Feedback Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedbackCommentCreate" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "get": { "tags": [ "Feedback" ], "summary": "List Comments", "description": "Get all comments for a feedback item.", "operationId": "feedback_list_comments", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "feedback_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Feedback Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedbackCommentListResponse" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/feedback/admin/{feedback_id}": { "patch": { "tags": [ "Feedback" ], "summary": "Update Feedback", "description": "Update feedback status and admin response (admin only).", "operationId": "feedback_update_feedback", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "feedback_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Feedback Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedbackUpdate" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedbackResponse" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/feedback/admin/{feedback_id}/internal-note": { "post": { "tags": [ "Feedback" ], "summary": "Add Internal Note", "description": "Add an internal-only note to a feedback item (admin only).\n\nInternal notes are hidden from non-admin users.", "operationId": "feedback_add_internal_note", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "feedback_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Feedback Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedbackCommentCreate" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/feedback/admin/{feedback_id}/events": { "get": { "tags": [ "Feedback" ], "summary": "Get Feedback Events", "description": "Get the audit trail for a feedback item (admin only).\n\nReturns all lifecycle events: status changes, priority changes, admin actions.", "operationId": "feedback_get_feedback_events", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "feedback_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Feedback Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/FeedbackEventResponse" }, "title": "Response Get Feedback Events V1 Feedback Admin Feedback Id Events Get" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/attachments": { "post": { "tags": [ "Attachments" ], "summary": "Upload Attachment", "description": "Upload a single file. Returns metadata dict to store with the feedback item.", "operationId": "attachments_upload_attachment", "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_upload_attachment_v1_attachments_post" } } }, "required": true }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "HTTPBearer": [] } ] }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/attachments/{stored_name}": { "get": { "tags": [ "Attachments" ], "summary": "Download Attachment", "description": "Download an attachment (auth-gated, never served as a static file).", "operationId": "attachments_download_attachment", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "stored_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Stored Name" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/attachments/config/limits": { "get": { "tags": [ "Attachments" ], "summary": "Get Attachment Limits", "description": "Return upload constraints for the frontend.", "operationId": "attachments_get_attachment_limits", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/notifications": { "get": { "tags": [ "Notifications" ], "summary": "List Notifications", "description": "List notifications for the current user.", "operationId": "notifications_list_notifications", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Offset" } }, { "name": "unread_only", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Unread Only" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationListResponse" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/notifications/unread-count": { "get": { "tags": [ "Notifications" ], "summary": "Get Unread Count", "description": "Return the unread notification count for the current user.", "operationId": "notifications_get_unread_count", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationCountResponse" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "HTTPBearer": [] } ] }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/notifications/{notification_id}/read": { "post": { "tags": [ "Notifications" ], "summary": "Mark Notification Read", "description": "Mark a single notification as read.", "operationId": "notifications_mark_notification_read", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "notification_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Notification Id" } } ], "responses": { "204": { "description": "Successful Response" }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/notifications/read-all": { "post": { "tags": [ "Notifications" ], "summary": "Mark All Notifications Read", "description": "Mark every notification for the current user as read.", "operationId": "notifications_mark_all_notifications_read", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationCountResponse" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "HTTPBearer": [] } ] }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/currency/rate": { "get": { "tags": [ "Currency" ], "summary": "Get Fx Rate", "description": "Return the cached USD -> ``target`` exchange rate.\n\nAlways returns 1.0 when ``target=USD``. Falls back to a sensible static\nrate if the upstream FX provider is unreachable.", "operationId": "currency_get_fx_rate", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "target", "in": "query", "required": true, "schema": { "type": "string", "description": "Target currency code (e.g. INR, USD)", "title": "Target" }, "description": "Target currency code (e.g. INR, USD)" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FxRateResponse" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/integrations/openai/costs": { "post": { "tags": [ "Integrations" ], "summary": "Import Openai Costs", "description": "Import retroactive costs from OpenAI's organization costs API.\n\nRequires an OpenAI **Admin** key (starts with sk-admin-) from\nplatform.openai.com/settings/organization/admin-keys. The key is used for\nthis request only - it is never stored or logged.", "operationId": "integrations_import_openai_costs", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAICostImportRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAICostImportResponse" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "HTTPBearer": [] } ] }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/integrations/anthropic/costs": { "post": { "tags": [ "Integrations" ], "summary": "Import Anthropic Costs", "description": "Import retroactive costs from Anthropic's organization cost report API.\n\nRequires an Anthropic **Admin** key (starts with sk-ant-admin-) from\nconsole.anthropic.com -> Settings -> Admin keys. The key is used for this\nrequest only - it is never stored or logged.", "operationId": "integrations_import_anthropic_costs", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicCostImportRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAICostImportResponse" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "HTTPBearer": [] } ] }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/metrics": { "get": { "tags": [ "Metrics" ], "summary": "Prometheus Metrics", "description": "Prometheus exposition of this project's cost metrics.\n\nAuthenticated with the project API key. Point a scrape job at it:\n\n scrape_configs:\n - job_name: agentcost\n metrics_path: /v1/metrics\n authorization:\n credentials: \n static_configs:\n - targets: ['api.agentcost.tech']\n\nValues are windowed counters, not monotonic ones — `window_hours` sets the\nlookback. Use them with `max_over_time` style queries rather than `rate()`,\nwhich assumes a counter that only ever climbs.", "operationId": "metrics_prometheus_metrics", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "window_hours", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 720, "minimum": 1, "description": "Aggregation window in hours", "default": 24, "title": "Window Hours" }, "description": "Aggregation window in hours" }, { "name": "project_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Project ID. Required for JWT-authenticated requests; ignored for SDK API-key requests (the project is derived from the key).", "title": "Project Id" }, "description": "Project ID. Required for JWT-authenticated requests; ignored for SDK API-key requests (the project is derived from the key)." } ], "responses": { "200": { "description": "Successful Response", "content": { "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/admin/auth/verify": { "get": { "tags": [ "Admin" ], "summary": "Verify Admin", "description": "Verify that the current token belongs to a superuser.", "operationId": "admin_verify_admin", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "HTTPBearer": [] } ] }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/admin/overview/stats": { "get": { "tags": [ "Admin" ], "summary": "Get Platform Stats", "description": "Aggregated platform-wide statistics.", "operationId": "admin_get_platform_stats", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "HTTPBearer": [] } ] }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/admin/overview/timeseries": { "get": { "tags": [ "Admin" ], "summary": "Get Platform Timeseries", "description": "Platform-wide daily timeseries: events, cost, tokens.", "operationId": "admin_get_platform_timeseries", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "range", "in": "query", "required": false, "schema": { "type": "string", "description": "Time range: 7d, 30d, 90d", "default": "30d", "title": "Range" }, "description": "Time range: 7d, 30d, 90d" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/admin/users": { "get": { "tags": [ "Admin" ], "summary": "List Users", "description": "List all users with search, filter, and pagination.", "operationId": "admin_list_users", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "search", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Search by email or name", "title": "Search" }, "description": "Search by email or name" }, { "name": "is_active", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Active" } }, { "name": "is_superuser", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Superuser" } }, { "name": "include_deleted", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Include soft-deleted users", "default": false, "title": "Include Deleted" }, "description": "Include soft-deleted users" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Offset" } }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "description": "Sort field", "default": "created_at", "title": "Sort" }, "description": "Sort field" }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "description": "asc or desc", "default": "desc", "title": "Order" }, "description": "asc or desc" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/admin/users/{user_id}": { "get": { "tags": [ "Admin" ], "summary": "Get User Detail", "description": "Full user profile with project memberships and usage footprint.", "operationId": "admin_get_user_detail", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string", "title": "User Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "patch": { "tags": [ "Admin" ], "summary": "Update User", "description": "Admin user update: toggle is_active, is_superuser.", "operationId": "admin_update_user", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string", "title": "User Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminUserUpdate" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "delete": { "tags": [ "Admin" ], "summary": "Delete User", "description": "Delete a user. Performs soft-delete by default (marks as deleted).\nPass ?permanent=true to permanently remove the user and all associated data.\nCannot delete superuser accounts or your own account.", "operationId": "admin_delete_user", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string", "title": "User Id" } }, { "name": "permanent", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Permanently delete instead of soft-delete", "default": false, "title": "Permanent" }, "description": "Permanently delete instead of soft-delete" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/admin/users/{user_id}/revoke-sessions": { "post": { "tags": [ "Admin" ], "summary": "Revoke User Sessions", "description": "Revoke all active sessions for a user.", "operationId": "admin_revoke_user_sessions", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string", "title": "User Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/admin/users/{user_id}/notes": { "put": { "tags": [ "Admin" ], "summary": "Set Admin Notes", "description": "Update the internal admin notes for a user.", "operationId": "admin_set_admin_notes", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string", "title": "User Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminNotesUpdate" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/admin/users/{user_id}/send-email": { "post": { "tags": [ "Admin" ], "summary": "Send Email To User", "description": "Send a direct email to a user from the admin panel.", "operationId": "admin_send_email_to_user", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string", "title": "User Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminEmailBody" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/admin/projects": { "get": { "tags": [ "Admin" ], "summary": "List Projects", "description": "List all projects with owner info and usage stats.", "operationId": "admin_list_projects", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "search", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Search" } }, { "name": "is_active", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Active" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Offset" } }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "default": "created_at", "title": "Sort" } }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "default": "desc", "title": "Order" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/admin/projects/{project_id}": { "get": { "tags": [ "Admin" ], "summary": "Get Project Detail", "description": "Detailed project view with members, usage, and key info.", "operationId": "admin_get_project_detail", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Project Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "patch": { "tags": [ "Admin" ], "summary": "Update Project", "description": "Admin update: toggle is_active (freeze/unfreeze ingestion).", "operationId": "admin_update_project", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Project Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminProjectUpdate" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/admin/projects/{project_id}/rotate-key": { "post": { "tags": [ "Admin" ], "summary": "Rotate Project Key", "description": "Rotate (regenerate) a project's API key.", "operationId": "admin_rotate_project_key", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Project Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/admin/projects/{project_id}/revoke-key": { "post": { "tags": [ "Admin" ], "summary": "Revoke Project Key", "description": "Revoke a project key and deactivate the project.", "operationId": "admin_revoke_project_key", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Project Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/admin/pricing/models": { "get": { "tags": [ "Admin" ], "summary": "List Pricing Models", "description": "List all model pricing records with filters.", "operationId": "admin_list_pricing_models", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "search", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Search" } }, { "name": "provider", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Provider" } }, { "name": "source", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 500, "minimum": 1, "default": 100, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Offset" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/admin/pricing/providers": { "get": { "tags": [ "Admin" ], "summary": "List Pricing Providers", "description": "Get provider summary with model counts and avg pricing.", "operationId": "admin_list_pricing_providers", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "HTTPBearer": [] } ] }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/admin/pricing/models/{model_id}": { "patch": { "tags": [ "Admin" ], "summary": "Update Model Pricing", "description": "Admin override for model pricing.\nSupports: input_price_per_1k, output_price_per_1k, is_active, notes.\nSets pricing_source to 'admin_override' when a price actually changes.", "operationId": "admin_update_model_pricing", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "model_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Model Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelPricingUpdate" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/admin/pricing/sync/litellm": { "post": { "tags": [ "Admin" ], "summary": "Sync Litellm Pricing", "description": "Trigger manual LiteLLM pricing sync with full audit trail.", "operationId": "admin_sync_litellm_pricing", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "HTTPBearer": [] } ] }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/admin/pricing/sync/openrouter": { "post": { "tags": [ "Admin" ], "summary": "Sync Openrouter Pricing", "description": "Trigger manual OpenRouter pricing sync with full audit trail.", "operationId": "admin_sync_openrouter_pricing", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "HTTPBearer": [] } ] }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/admin/pricing/sync-history": { "get": { "tags": [ "Admin" ], "summary": "Get Sync History", "description": "Get pricing sync history with detailed change records.", "operationId": "admin_get_sync_history", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "source", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 20, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Offset" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/admin/system/health": { "get": { "tags": [ "Admin" ], "summary": "System Health", "description": "System health: db connectivity, table counts, uptime indicators.", "operationId": "admin_system_health", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "HTTPBearer": [] } ] }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/admin/system/ingestion-stats": { "get": { "tags": [ "Admin" ], "summary": "Ingestion Stats", "description": "Ingestion throughput stats over time.", "operationId": "admin_ingestion_stats", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "range", "in": "query", "required": false, "schema": { "type": "string", "description": "Time range: 1h, 24h, 7d", "default": "24h", "title": "Range" }, "description": "Time range: 1h, 24h, 7d" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/admin/analytics/top-models": { "get": { "tags": [ "Admin" ], "summary": "Top Models", "description": "Most used models across all tenants.", "operationId": "admin_top_models", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "range", "in": "query", "required": false, "schema": { "type": "string", "default": "30d", "title": "Range" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 20, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/admin/analytics/top-spenders": { "get": { "tags": [ "Admin" ], "summary": "Top Spenders", "description": "Highest spend tenants (by project).", "operationId": "admin_top_spenders", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "range", "in": "query", "required": false, "schema": { "type": "string", "default": "30d", "title": "Range" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 20, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/admin/analytics/provider-growth": { "get": { "tags": [ "Admin" ], "summary": "Provider Growth", "description": "Provider usage growth over time.", "operationId": "admin_provider_growth", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "range", "in": "query", "required": false, "schema": { "type": "string", "default": "30d", "title": "Range" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/admin/analytics/cost-per-user": { "get": { "tags": [ "Admin" ], "summary": "Avg Cost Per User", "description": "Average cost per user across the platform.", "operationId": "admin_avg_cost_per_user", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "range", "in": "query", "required": false, "schema": { "type": "string", "default": "30d", "title": "Range" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/admin/incidents/events": { "get": { "tags": [ "Admin" ], "summary": "Failed Events", "description": "Failed event ingestions (success=False).", "operationId": "admin_failed_events", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Offset" } }, { "name": "project_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Project Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/admin/incidents/feedback": { "get": { "tags": [ "Admin" ], "summary": "Feedback Incidents", "description": "Bug reports and incident-type feedback.", "operationId": "admin_feedback_incidents", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" } }, { "name": "priority", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Priority" } }, { "name": "type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Type" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Offset" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/admin/feedback": { "get": { "tags": [ "Admin" ], "summary": "List All Feedback", "description": "List all feedback with filtering by status, priority, type, and search.\nUnlike /incidents/feedback this returns ALL feedback types.", "operationId": "admin_list_all_feedback", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" } }, { "name": "priority", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Priority" } }, { "name": "type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Type" } }, { "name": "search", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Search" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Offset" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/admin/feedback/{feedback_id}": { "get": { "tags": [ "Admin" ], "summary": "Get Feedback Detail", "description": "Full feedback detail including comments and event history.", "operationId": "admin_get_feedback_detail", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "feedback_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Feedback Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "patch": { "tags": [ "Admin" ], "summary": "Patch Feedback", "description": "Update feedback status, priority, and/or admin response.\nSends an email notification to the user when a response is provided.", "operationId": "admin_patch_feedback", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "feedback_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Feedback Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Body" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/admin/audit-log": { "get": { "tags": [ "Admin" ], "summary": "Get Audit Log", "description": "Retrieve the admin activity audit trail.\nSupports filtering by action_type, target_type, and actor.", "operationId": "admin_get_audit_log", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "action_type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Action Type" } }, { "name": "target_type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Target Type" } }, { "name": "admin_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Admin Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Offset" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/admin/demo/stats": { "get": { "tags": [ "Admin" ], "summary": "Get Demo Stats", "description": "Aggregated demo usage and conversion statistics.", "operationId": "admin_get_demo_stats", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "HTTPBearer": [] } ] }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/admin/demo/timeseries": { "get": { "tags": [ "Admin" ], "summary": "Get Demo Timeseries", "description": "Daily demo sessions and conversions for the admin chart.", "operationId": "admin_get_demo_timeseries", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "range", "in": "query", "required": false, "schema": { "type": "string", "description": "Time range: 7d, 30d, 90d", "default": "30d", "title": "Range" }, "description": "Time range: 7d, 30d, 90d" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/demo/track": { "post": { "tags": [ "Demo" ], "summary": "Track Demo Event", "description": "Record a demo-mode event. Public endpoint, no auth, no PII.", "operationId": "demo_track_demo_event", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DemoTrackRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/health": { "get": { "tags": [ "Health" ], "summary": "Health Check", "description": "Health check endpoint.\n\nReturns server status and version.", "operationId": "health_health_check", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" } } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/": { "get": { "tags": [ "Root" ], "summary": "Root", "description": "Root endpoint with API information", "operationId": "root_root", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "429": { "description": "Rate limit exceeded. See the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "servers": [ { "url": "https://api.agentcost.tech", "description": "AgentCost API (origin). Sleeps when idle; a cold request can take ~60s." } ] }, "/v1/estimate": { "servers": [ { "url": "https://agentcost.tech/api", "description": "Cached mirror on the website. Serves the public read endpoints and the cost estimator, and does not sleep." } ], "post": { "tags": [ "Pricing" ], "operationId": "pricing_estimate_cost", "summary": "Estimate the cost of a call", "description": "Estimate what a model call will cost before making it, from the current public catalogue. Rates are per 1,000 tokens in USD. Cached input tokens are billed at the provider's cached rate when one is published and at the full input rate when it is not — `cached_billed_at_input_rate` reports which happened. Multiply a single call out to a whole job with `calls`. No credentials required.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EstimateRequest" }, "examples": { "singleCall": { "summary": "One call to gpt-4o", "value": { "model": "gpt-4o", "input_tokens": 12000, "output_tokens": 800 } }, "wholeJob": { "summary": "1,000 runs of the same step, with a warm prompt cache", "value": { "model": "claude-sonnet-4-6", "input_tokens": 2000, "output_tokens": 400, "cached_input_tokens": 18000, "calls": 1000 } } } } } }, "responses": { "200": { "description": "The estimate, with the rates and catalogue entry it was based on.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Estimate" } } } }, "404": { "description": "The model is not in the catalogue.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "The request body failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "The catalogue is temporarily unreachable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } } }, "components": { "schemas": { "AdminEmailBody": { "properties": { "subject": { "type": "string", "maxLength": 500, "minLength": 1, "title": "Subject" }, "body": { "type": "string", "maxLength": 50000, "minLength": 1, "title": "Body" } }, "type": "object", "required": [ "subject", "body" ], "title": "AdminEmailBody", "description": "Typed body for admin direct email." }, "AdminNotesUpdate": { "properties": { "notes": { "type": "string", "maxLength": 10000, "title": "Notes", "default": "" } }, "type": "object", "title": "AdminNotesUpdate", "description": "Typed body for admin notes update." }, "AdminProjectUpdate": { "properties": { "is_active": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Active" } }, "type": "object", "title": "AdminProjectUpdate", "description": "Typed body for admin project update." }, "AdminUserUpdate": { "properties": { "is_active": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Active" }, "is_superuser": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Superuser" } }, "type": "object", "title": "AdminUserUpdate", "description": "Typed body for admin user update." }, "AgentStats": { "properties": { "agent_name": { "type": "string", "title": "Agent Name" }, "total_calls": { "type": "integer", "title": "Total Calls" }, "total_tokens": { "type": "integer", "title": "Total Tokens" }, "total_cost": { "type": "number", "title": "Total Cost" }, "avg_latency_ms": { "type": "number", "title": "Avg Latency Ms" }, "success_rate": { "type": "number", "title": "Success Rate" } }, "type": "object", "required": [ "agent_name", "total_calls", "total_tokens", "total_cost", "avg_latency_ms", "success_rate" ], "title": "AgentStats", "description": "Stats for a single agent" }, "AnalyticsOverview": { "properties": { "total_cost": { "type": "number", "title": "Total Cost" }, "total_calls": { "type": "integer", "title": "Total Calls" }, "total_tokens": { "type": "integer", "title": "Total Tokens" }, "total_input_tokens": { "type": "integer", "title": "Total Input Tokens", "default": 0 }, "total_output_tokens": { "type": "integer", "title": "Total Output Tokens", "default": 0 }, "avg_cost_per_call": { "type": "number", "title": "Avg Cost Per Call" }, "avg_tokens_per_call": { "type": "number", "title": "Avg Tokens Per Call", "default": 0 }, "avg_latency_ms": { "type": "number", "title": "Avg Latency Ms" }, "success_rate": { "type": "number", "title": "Success Rate" }, "period_start": { "type": "string", "format": "date-time", "title": "Period Start" }, "period_end": { "type": "string", "format": "date-time", "title": "Period End" } }, "type": "object", "required": [ "total_cost", "total_calls", "total_tokens", "avg_cost_per_call", "avg_latency_ms", "success_rate", "period_start", "period_end" ], "title": "AnalyticsOverview", "description": "Overview analytics response" }, "AnalyticsResponse": { "properties": { "overview": { "$ref": "#/components/schemas/AnalyticsOverview" }, "agents": { "items": { "$ref": "#/components/schemas/AgentStats" }, "type": "array", "title": "Agents" }, "models": { "items": { "$ref": "#/components/schemas/ModelStats" }, "type": "array", "title": "Models" }, "timeseries": { "items": { "$ref": "#/components/schemas/TimeSeriesPoint" }, "type": "array", "title": "Timeseries" } }, "type": "object", "required": [ "overview", "agents", "models", "timeseries" ], "title": "AnalyticsResponse", "description": "Full analytics response" }, "AnthropicCostImportRequest": { "properties": { "api_key": { "type": "string", "title": "Api Key", "description": "Anthropic Admin API key (used once, never stored)" }, "days": { "type": "integer", "title": "Days", "description": "How many days back to import (clamped to 1-90)", "default": 30 } }, "type": "object", "required": [ "api_key" ], "title": "AnthropicCostImportRequest", "description": "Request to import retroactive costs from Anthropic's cost report API" }, "Body_upload_attachment_v1_attachments_post": { "properties": { "file": { "type": "string", "format": "binary", "title": "File" } }, "type": "object", "required": [ "file" ], "title": "Body_upload_attachment_v1_attachments_post" }, "BudgetStatus": { "properties": { "enabled": { "type": "boolean", "title": "Enabled" }, "budget": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Budget" }, "current_spend": { "type": "number", "title": "Current Spend", "default": 0 }, "projected_spend": { "type": "number", "title": "Projected Spend", "default": 0 }, "utilization_percent": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Utilization Percent" }, "currency": { "type": "string", "title": "Currency", "default": "USD" }, "fx_rate": { "type": "number", "title": "Fx Rate", "default": 1 }, "mode": { "type": "string", "title": "Mode", "default": "off" } }, "type": "object", "required": [ "enabled" ], "title": "BudgetStatus" }, "CacheAnalytics": { "properties": { "total_input_tokens": { "type": "integer", "title": "Total Input Tokens" }, "cached_tokens": { "type": "integer", "title": "Cached Tokens" }, "cache_write_tokens": { "type": "integer", "title": "Cache Write Tokens" }, "cache_hit_rate": { "type": "number", "title": "Cache Hit Rate" }, "events_with_cache": { "type": "integer", "title": "Events With Cache" }, "read_savings": { "type": "number", "title": "Read Savings" }, "write_premium": { "type": "number", "title": "Write Premium" }, "net_savings": { "type": "number", "title": "Net Savings" } }, "type": "object", "required": [ "total_input_tokens", "cached_tokens", "cache_write_tokens", "cache_hit_rate", "events_with_cache", "read_savings", "write_premium", "net_savings" ], "title": "CacheAnalytics", "description": "Prompt-cache performance and savings over a window, in USD.\n\n``read_savings`` compares actual cost against billing every cached token\nat the full input rate; ``write_premium`` is the extra paid for cache\nwrites over the same baseline. Models with no published cache rate\ncontribute zero to both." }, "CadenceBucket": { "properties": { "label": { "type": "string", "title": "Label" }, "index": { "type": "integer", "title": "Index" }, "calls": { "type": "integer", "title": "Calls" }, "cost": { "type": "number", "title": "Cost" } }, "type": "object", "required": [ "label", "index", "calls", "cost" ], "title": "CadenceBucket" }, "DailyCost": { "properties": { "date": { "type": "string", "title": "Date" }, "amount_usd": { "type": "number", "title": "Amount Usd" } }, "type": "object", "required": [ "date", "amount_usd" ], "title": "DailyCost", "description": "Cost total for a single day" }, "DefaultProjectInfo": { "properties": { "id": { "type": "string", "title": "Id" }, "name": { "type": "string", "title": "Name" }, "api_key": { "type": "string", "title": "Api Key" } }, "type": "object", "required": [ "id", "name", "api_key" ], "title": "DefaultProjectInfo", "description": "Default project created at registration (api_key shown ONCE, never again)" }, "DemoTrackRequest": { "properties": { "session_id": { "type": "string", "maxLength": 64, "minLength": 8, "title": "Session Id" }, "event_type": { "type": "string", "enum": [ "demo_start", "page_view", "signup_click", "signup_completed", "demo_exit" ], "title": "Event Type" }, "page": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "Page" }, "source": { "anyOf": [ { "type": "string", "maxLength": 50 }, { "type": "null" } ], "title": "Source" }, "referrer": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "null" } ], "title": "Referrer" } }, "type": "object", "required": [ "session_id", "event_type" ], "title": "DemoTrackRequest" }, "DeprecationEntry": { "properties": { "model": { "type": "string", "title": "Model", "description": "Model name." }, "provider": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Provider", "description": "Provider slug." }, "deprecation_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Deprecation Date", "description": "Announced retirement date, YYYY-MM-DD." }, "mode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Mode", "description": "Model modality." } }, "type": "object", "required": [ "model" ], "title": "DeprecationEntry", "description": "A model with an announced retirement date." }, "DeprecationsResponse": { "properties": { "deprecations": { "items": { "$ref": "#/components/schemas/DeprecationEntry" }, "type": "array", "title": "Deprecations", "description": "Ordered by date ascending, then model name." }, "count": { "type": "integer", "title": "Count", "description": "Number of entries returned." } }, "type": "object", "required": [ "deprecations", "count" ], "title": "DeprecationsResponse", "description": "Active models with an announced retirement date, soonest first." }, "DimensionStat": { "properties": { "key": { "type": "string", "title": "Key" }, "total_calls": { "type": "integer", "title": "Total Calls" }, "total_tokens": { "type": "integer", "title": "Total Tokens" }, "total_cost": { "type": "number", "title": "Total Cost" }, "avg_latency_ms": { "type": "number", "title": "Avg Latency Ms" }, "success_rate": { "type": "number", "title": "Success Rate" } }, "type": "object", "required": [ "key", "total_calls", "total_tokens", "total_cost", "avg_latency_ms", "success_rate" ], "title": "DimensionStat", "description": "Aggregates for one value of a grouping dimension." }, "EmailVerificationRequest": { "properties": { "token": { "type": "string", "title": "Token", "description": "Email verification token" } }, "type": "object", "required": [ "token" ], "title": "EmailVerificationRequest", "description": "Email verification request" }, "ErrorBreakdownRow": { "properties": { "model": { "type": "string", "title": "Model" }, "total_calls": { "type": "integer", "title": "Total Calls" }, "error_count": { "type": "integer", "title": "Error Count" }, "error_rate": { "type": "number", "title": "Error Rate" } }, "type": "object", "required": [ "model", "total_calls", "error_count", "error_rate" ], "title": "ErrorBreakdownRow" }, "EventBatchRequest": { "properties": { "project_id": { "type": "string", "minLength": 1, "title": "Project Id" }, "events": { "items": { "$ref": "#/components/schemas/EventCreate" }, "type": "array", "maxItems": 1000, "title": "Events" }, "outcomes": { "items": { "$ref": "#/components/schemas/OutcomeCreate" }, "type": "array", "maxItems": 1000, "title": "Outcomes" } }, "type": "object", "required": [ "project_id" ], "title": "EventBatchRequest", "description": "Request body for batch event ingestion\n\nNote: The effective max batch size is enforced by config.max_batch_size\n(default 100) at the route level against ``received_count``. The schema\nallows up to 1000 as an upper safety net." }, "EventBatchResponse": { "properties": { "status": { "type": "string", "title": "Status", "default": "ok" }, "events_stored": { "type": "integer", "title": "Events Stored" }, "timestamp": { "type": "string", "title": "Timestamp" }, "events_received": { "type": "integer", "title": "Events Received", "default": 0 }, "events_rejected": { "type": "integer", "title": "Events Rejected", "default": 0 }, "events_duplicate": { "type": "integer", "title": "Events Duplicate", "default": 0 }, "outcomes_recorded": { "type": "integer", "title": "Outcomes Recorded", "default": 0 }, "rejected": { "items": { "$ref": "#/components/schemas/RejectedEvent" }, "type": "array", "title": "Rejected" } }, "type": "object", "required": [ "events_stored", "timestamp" ], "title": "EventBatchResponse", "description": "Response for batch event ingestion\n\n``status``/``events_stored``/``timestamp`` are the contract the SDK parses\n(it only treats ``status == \"ok\"`` as success); the rejection fields are\nadditive so older SDKs keep working." }, "EventCreate": { "properties": { "agent_name": { "type": "string", "maxLength": 255, "title": "Agent Name", "default": "default" }, "model": { "type": "string", "maxLength": 255, "title": "Model" }, "input_tokens": { "type": "integer", "minimum": 0, "title": "Input Tokens" }, "output_tokens": { "type": "integer", "minimum": 0, "title": "Output Tokens" }, "total_tokens": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ], "title": "Total Tokens" }, "cached_tokens": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ], "title": "Cached Tokens" }, "cache_write_tokens": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ], "title": "Cache Write Tokens" }, "streaming": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Streaming" }, "cost": { "type": "number", "minimum": 0, "title": "Cost", "default": 0 }, "latency_ms": { "type": "integer", "minimum": 0, "title": "Latency Ms", "default": 0 }, "timestamp": { "type": "string", "title": "Timestamp" }, "success": { "type": "boolean", "title": "Success", "default": true }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata" }, "input_hash": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ], "title": "Input Hash" }, "event_id": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ], "title": "Event Id" }, "trace_id": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ], "title": "Trace Id" }, "span_id": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ], "title": "Span Id" }, "parent_span_id": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ], "title": "Parent Span Id" }, "workflow": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "Workflow" }, "step_name": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "Step Name" }, "step_index": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ], "title": "Step Index" }, "depth": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ], "title": "Depth" }, "tool_name": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "Tool Name" } }, "type": "object", "required": [ "model", "input_tokens", "output_tokens", "timestamp" ], "title": "EventCreate", "description": "Schema for a single event in batch" }, "EventResponse": { "properties": { "id": { "type": "string", "title": "Id" }, "agent_name": { "type": "string", "title": "Agent Name" }, "model": { "type": "string", "title": "Model" }, "input_tokens": { "type": "integer", "title": "Input Tokens" }, "output_tokens": { "type": "integer", "title": "Output Tokens" }, "total_tokens": { "type": "integer", "title": "Total Tokens" }, "cost": { "type": "number", "title": "Cost" }, "latency_ms": { "type": "integer", "title": "Latency Ms" }, "timestamp": { "type": "string", "title": "Timestamp" }, "success": { "type": "boolean", "title": "Success" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" }, "extra_data": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Extra Data" }, "trace_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Trace Id" }, "workflow": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Workflow" }, "step_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Step Name" }, "tool_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tool Name" } }, "type": "object", "required": [ "id", "agent_name", "model", "input_tokens", "output_tokens", "total_tokens", "cost", "latency_ms", "timestamp", "success" ], "title": "EventResponse", "description": "Single event response" }, "ExecutiveReport": { "properties": { "generated_at": { "type": "string", "format": "date-time", "title": "Generated At" }, "range_label": { "type": "string", "title": "Range Label" }, "period_start": { "type": "string", "format": "date-time", "title": "Period Start" }, "period_end": { "type": "string", "format": "date-time", "title": "Period End" }, "previous_period_start": { "type": "string", "format": "date-time", "title": "Previous Period Start" }, "previous_period_end": { "type": "string", "format": "date-time", "title": "Previous Period End" }, "is_custom_range": { "type": "boolean", "title": "Is Custom Range", "default": false }, "project_name": { "type": "string", "title": "Project Name" }, "currency": { "type": "string", "title": "Currency", "default": "USD" }, "summary": { "$ref": "#/components/schemas/ReportSummary" }, "overview": { "$ref": "#/components/schemas/AnalyticsOverview" }, "timeseries": { "items": { "$ref": "#/components/schemas/TimeSeriesPoint" }, "type": "array", "title": "Timeseries" }, "models": { "items": { "$ref": "#/components/schemas/ModelStats" }, "type": "array", "title": "Models" }, "model_pareto": { "$ref": "#/components/schemas/ParetoInfo" }, "agents": { "items": { "$ref": "#/components/schemas/AgentStats" }, "type": "array", "title": "Agents" }, "agent_cost_share": { "additionalProperties": { "type": "number" }, "type": "object", "title": "Agent Cost Share" }, "latency": { "$ref": "#/components/schemas/LatencyPercentiles" }, "efficiency": { "$ref": "#/components/schemas/TokenEfficiency" }, "errors": { "items": { "$ref": "#/components/schemas/ErrorBreakdownRow" }, "type": "array", "title": "Errors" }, "top_errors": { "items": { "$ref": "#/components/schemas/TopError" }, "type": "array", "title": "Top Errors" }, "cadence": { "$ref": "#/components/schemas/UsageCadence" }, "run_rate": { "$ref": "#/components/schemas/RunRateProjection" }, "budget": { "$ref": "#/components/schemas/BudgetStatus" }, "savings": { "$ref": "#/components/schemas/SavingsRollup" } }, "type": "object", "required": [ "generated_at", "range_label", "period_start", "period_end", "previous_period_start", "previous_period_end", "project_name", "summary", "overview", "timeseries", "models", "model_pareto", "agents", "agent_cost_share", "latency", "efficiency", "errors", "top_errors", "cadence", "run_rate", "budget", "savings" ], "title": "ExecutiveReport", "description": "Board-ready cost & usage report: executive summary + deep breakdowns." }, "FeedbackCommentCreate": { "properties": { "comment": { "type": "string", "maxLength": 2000, "minLength": 1, "title": "Comment" }, "user_name": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "User Name" } }, "type": "object", "required": [ "comment" ], "title": "FeedbackCommentCreate" }, "FeedbackCommentListResponse": { "properties": { "items": { "items": { "$ref": "#/components/schemas/FeedbackCommentResponse" }, "type": "array", "title": "Items" }, "total": { "type": "integer", "title": "Total" } }, "type": "object", "required": [ "items", "total" ], "title": "FeedbackCommentListResponse" }, "FeedbackCommentResponse": { "properties": { "id": { "type": "string", "title": "Id" }, "user_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User Name" }, "comment": { "type": "string", "title": "Comment" }, "is_admin": { "type": "boolean", "title": "Is Admin" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" } }, "type": "object", "required": [ "id", "user_name", "comment", "is_admin", "created_at" ], "title": "FeedbackCommentResponse" }, "FeedbackCreate": { "properties": { "type": { "type": "string", "enum": [ "feature_request", "bug_report", "model_request", "general", "security_report", "performance_issue" ], "title": "Type" }, "title": { "type": "string", "maxLength": 255, "minLength": 3, "title": "Title" }, "description": { "type": "string", "maxLength": 5000, "minLength": 10, "title": "Description" }, "model_name": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "Model Name" }, "model_provider": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ], "title": "Model Provider" }, "user_email": { "anyOf": [ { "type": "string", "maxLength": 255, "format": "email" }, { "type": "null" } ], "title": "User Email" }, "user_name": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "User Name" }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata" }, "attachments": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Attachments" }, "environment": { "anyOf": [ { "type": "string", "maxLength": 50 }, { "type": "null" } ], "title": "Environment" }, "client_metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Client Metadata" } }, "type": "object", "required": [ "type", "title", "description" ], "title": "FeedbackCreate", "description": "Submit feedback or a request." }, "FeedbackCreatedResponse": { "properties": { "id": { "type": "string", "title": "Id" }, "message": { "type": "string", "title": "Message" } }, "type": "object", "required": [ "id", "message" ], "title": "FeedbackCreatedResponse" }, "FeedbackEventResponse": { "properties": { "id": { "type": "string", "title": "Id" }, "feedback_id": { "type": "string", "title": "Feedback Id" }, "event_type": { "type": "string", "title": "Event Type" }, "old_value": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Old Value" }, "new_value": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "New Value" }, "actor_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Actor Id" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" } }, "type": "object", "required": [ "id", "feedback_id", "event_type", "created_at" ], "title": "FeedbackEventResponse", "description": "Audit trail event for a feedback item." }, "FeedbackListResponse": { "properties": { "items": { "items": { "$ref": "#/components/schemas/FeedbackResponse" }, "type": "array", "title": "Items" }, "total": { "type": "integer", "title": "Total" }, "limit": { "type": "integer", "title": "Limit" }, "offset": { "type": "integer", "title": "Offset" } }, "type": "object", "required": [ "items", "total", "limit", "offset" ], "title": "FeedbackListResponse" }, "FeedbackResponse": { "properties": { "id": { "type": "string", "title": "Id" }, "type": { "type": "string", "enum": [ "feature_request", "bug_report", "model_request", "general", "security_report", "performance_issue" ], "title": "Type" }, "title": { "type": "string", "title": "Title" }, "description": { "type": "string", "title": "Description" }, "status": { "type": "string", "enum": [ "open", "under_review", "needs_info", "in_progress", "completed", "shipped", "rejected", "duplicate" ], "title": "Status" }, "priority": { "type": "string", "enum": [ "low", "medium", "high", "critical" ], "title": "Priority" }, "upvotes": { "type": "integer", "title": "Upvotes" }, "user_has_upvoted": { "type": "boolean", "title": "User Has Upvoted" }, "model_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model Name" }, "model_provider": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model Provider" }, "admin_response": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Admin Response" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At" }, "comment_count": { "type": "integer", "title": "Comment Count" }, "user_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User Name" }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata" }, "attachments": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Attachments" }, "environment": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Environment" }, "is_confidential": { "type": "boolean", "title": "Is Confidential", "default": false } }, "type": "object", "required": [ "id", "type", "title", "description", "status", "priority", "upvotes", "user_has_upvoted", "model_name", "model_provider", "admin_response", "created_at", "updated_at", "comment_count" ], "title": "FeedbackResponse" }, "FeedbackSummaryResponse": { "properties": { "total": { "type": "integer", "title": "Total" }, "by_type": { "additionalProperties": { "type": "integer" }, "type": "object", "title": "By Type" }, "by_status": { "additionalProperties": { "type": "integer" }, "type": "object", "title": "By Status" } }, "type": "object", "required": [ "total", "by_type", "by_status" ], "title": "FeedbackSummaryResponse" }, "FeedbackUpdate": { "properties": { "status": { "type": "string", "enum": [ "open", "under_review", "needs_info", "in_progress", "completed", "shipped", "rejected", "duplicate" ], "title": "Status" }, "priority": { "anyOf": [ { "type": "string", "enum": [ "low", "medium", "high", "critical" ] }, { "type": "null" } ], "title": "Priority" }, "admin_response": { "anyOf": [ { "type": "string", "maxLength": 5000 }, { "type": "null" } ], "title": "Admin Response" } }, "type": "object", "required": [ "status" ], "title": "FeedbackUpdate", "description": "Admin update payload for feedback status and response." }, "FxRateResponse": { "properties": { "base": { "type": "string", "const": "USD", "title": "Base", "default": "USD" }, "target": { "type": "string", "title": "Target" }, "rate": { "type": "number", "title": "Rate" }, "source": { "type": "string", "title": "Source", "default": "frankfurter.dev" } }, "type": "object", "required": [ "target", "rate" ], "title": "FxRateResponse" }, "GitHubAuthRequest": { "properties": { "code": { "type": "string", "title": "Code", "description": "Authorization code from GitHub's OAuth redirect" }, "accept_terms": { "type": "boolean", "title": "Accept Terms", "description": "User accepts Terms of Service (implicit via GitHub sign-in)", "default": true }, "accept_privacy": { "type": "boolean", "title": "Accept Privacy", "description": "User accepts Privacy Policy (implicit via GitHub sign-in)", "default": true }, "terms_version": { "type": "string", "title": "Terms Version", "description": "Terms of Service version accepted", "default": "1.0" }, "privacy_version": { "type": "string", "title": "Privacy Version", "description": "Privacy Policy version accepted", "default": "1.0" } }, "type": "object", "required": [ "code" ], "title": "GitHubAuthRequest", "description": "GitHub OAuth sign-in/sign-up request" }, "GoogleAuthRequest": { "properties": { "credential": { "type": "string", "title": "Credential", "description": "Google ID token from Google Identity Services" }, "accept_terms": { "type": "boolean", "title": "Accept Terms", "description": "User accepts Terms of Service (implicit via Google sign-in)", "default": true }, "accept_privacy": { "type": "boolean", "title": "Accept Privacy", "description": "User accepts Privacy Policy (implicit via Google sign-in)", "default": true }, "terms_version": { "type": "string", "title": "Terms Version", "description": "Terms of Service version accepted", "default": "1.0" }, "privacy_version": { "type": "string", "title": "Privacy Version", "description": "Privacy Policy version accepted", "default": "1.0" } }, "type": "object", "required": [ "credential" ], "title": "GoogleAuthRequest", "description": "Google OAuth sign-in/sign-up request" }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "HealthResponse": { "properties": { "status": { "type": "string", "title": "Status", "default": "ok" }, "version": { "type": "string", "title": "Version" }, "timestamp": { "type": "string", "title": "Timestamp" } }, "type": "object", "required": [ "version", "timestamp" ], "title": "HealthResponse", "description": "Health check response" }, "InvitationResponse": { "properties": { "project_id": { "type": "string", "title": "Project Id" }, "project_name": { "type": "string", "title": "Project Name" }, "role": { "type": "string", "title": "Role" }, "invited_by": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Invited By" }, "invited_at": { "type": "string", "format": "date-time", "title": "Invited At" } }, "type": "object", "required": [ "project_id", "project_name", "role", "invited_by", "invited_at" ], "title": "InvitationResponse" }, "InvitationsListResponse": { "properties": { "invitations": { "items": { "$ref": "#/components/schemas/InvitationResponse" }, "type": "array", "title": "Invitations" }, "total": { "type": "integer", "title": "Total" } }, "type": "object", "required": [ "invitations", "total" ], "title": "InvitationsListResponse" }, "InviteMemberRequest": { "properties": { "email": { "type": "string", "format": "email", "title": "Email", "description": "Email of user to invite" }, "role": { "type": "string", "title": "Role", "description": "Role: admin, member, or viewer", "default": "member" } }, "type": "object", "required": [ "email" ], "title": "InviteMemberRequest" }, "LatencyPercentiles": { "properties": { "p50": { "type": "number", "title": "P50" }, "p95": { "type": "number", "title": "P95" }, "p99": { "type": "number", "title": "P99" }, "avg": { "type": "number", "title": "Avg" }, "sample_size": { "type": "integer", "title": "Sample Size" }, "approximate": { "type": "boolean", "title": "Approximate", "default": false } }, "type": "object", "required": [ "p50", "p95", "p99", "avg", "sample_size" ], "title": "LatencyPercentiles" }, "MemberResponse": { "properties": { "id": { "type": "string", "title": "Id" }, "user_id": { "type": "string", "title": "User Id" }, "email": { "type": "string", "title": "Email" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "role": { "type": "string", "title": "Role" }, "is_owner": { "type": "boolean", "title": "Is Owner" }, "is_pending": { "type": "boolean", "title": "Is Pending" }, "invited_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Invited At" }, "accepted_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Accepted At" } }, "type": "object", "required": [ "id", "user_id", "email", "name", "role", "is_owner", "is_pending", "invited_at", "accepted_at" ], "title": "MemberResponse" }, "MembersListResponse": { "properties": { "members": { "items": { "$ref": "#/components/schemas/MemberResponse" }, "type": "array", "title": "Members" }, "total": { "type": "integer", "title": "Total" } }, "type": "object", "required": [ "members", "total" ], "title": "MembersListResponse" }, "MetricDelta": { "properties": { "current": { "type": "number", "title": "Current" }, "previous": { "type": "number", "title": "Previous" }, "change_percent": { "type": "number", "title": "Change Percent" }, "direction": { "type": "string", "enum": [ "up", "down", "neutral" ], "title": "Direction" } }, "type": "object", "required": [ "current", "previous", "change_percent", "direction" ], "title": "MetricDelta", "description": "A headline metric with its prior-period comparison." }, "ModelEfficiency": { "properties": { "model": { "type": "string", "title": "Model" }, "cost_per_1k": { "type": "number", "title": "Cost Per 1K" }, "in_out_ratio": { "type": "number", "title": "In Out Ratio" } }, "type": "object", "required": [ "model", "cost_per_1k", "in_out_ratio" ], "title": "ModelEfficiency" }, "ModelPricingResponse": { "properties": { "model": { "type": "string", "title": "Model", "description": "The model name as requested." }, "matched_to": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Matched To", "description": "Catalogue entry the name resolved to, when the match was fuzzy rather than exact." }, "input": { "type": "number", "title": "Input", "description": "Cost per 1,000 input tokens, USD. 0.0 when unknown." }, "output": { "type": "number", "title": "Output", "description": "Cost per 1,000 output tokens, USD. 0.0 when unknown." }, "provider": { "type": "string", "title": "Provider", "description": "Provider slug, or \"unknown\" when the model is not in the catalogue." }, "source": { "type": "string", "title": "Source", "description": "\"database\", \"database-fuzzy\", or \"fallback\" when nothing matched." } }, "type": "object", "required": [ "model", "input", "output", "provider", "source" ], "title": "ModelPricingResponse", "description": "Rates for one model, resolved the same way event ingestion resolves them." }, "ModelPricingUpdate": { "properties": { "input_price_per_1k": { "anyOf": [ { "type": "number", "maximum": 10, "minimum": 0 }, { "type": "null" } ], "title": "Input Price Per 1K" }, "output_price_per_1k": { "anyOf": [ { "type": "number", "maximum": 10, "minimum": 0 }, { "type": "null" } ], "title": "Output Price Per 1K" }, "is_active": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Active" }, "notes": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ], "title": "Notes" } }, "additionalProperties": false, "type": "object", "title": "ModelPricingUpdate", "description": "Admin-supplied pricing override. Omitted fields are left unchanged." }, "ModelStats": { "properties": { "model": { "type": "string", "title": "Model" }, "total_calls": { "type": "integer", "title": "Total Calls" }, "total_tokens": { "type": "integer", "title": "Total Tokens" }, "input_tokens": { "type": "integer", "title": "Input Tokens" }, "output_tokens": { "type": "integer", "title": "Output Tokens" }, "total_cost": { "type": "number", "title": "Total Cost" }, "avg_latency_ms": { "type": "number", "title": "Avg Latency Ms" }, "cost_share": { "type": "number", "title": "Cost Share", "default": 0 } }, "type": "object", "required": [ "model", "total_calls", "total_tokens", "input_tokens", "output_tokens", "total_cost", "avg_latency_ms" ], "title": "ModelStats", "description": "Stats for a single model" }, "NotificationCountResponse": { "properties": { "unread_count": { "type": "integer", "title": "Unread Count" } }, "type": "object", "required": [ "unread_count" ], "title": "NotificationCountResponse" }, "NotificationListResponse": { "properties": { "items": { "items": { "$ref": "#/components/schemas/NotificationResponse" }, "type": "array", "title": "Items" }, "total": { "type": "integer", "title": "Total" }, "unread_count": { "type": "integer", "title": "Unread Count" } }, "type": "object", "required": [ "items", "total", "unread_count" ], "title": "NotificationListResponse" }, "NotificationResponse": { "properties": { "id": { "type": "string", "title": "Id" }, "type": { "type": "string", "title": "Type" }, "severity": { "type": "string", "enum": [ "info", "warning", "critical" ], "title": "Severity", "default": "info" }, "title": { "type": "string", "title": "Title" }, "body": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Body" }, "link": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Link" }, "project_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Project Id" }, "payload": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Payload" }, "is_read": { "type": "boolean", "title": "Is Read" }, "read_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Read At" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" } }, "type": "object", "required": [ "id", "type", "title", "is_read", "created_at" ], "title": "NotificationResponse", "description": "A single in-app notification." }, "OpenAICostImportRequest": { "properties": { "api_key": { "type": "string", "title": "Api Key", "description": "OpenAI Admin API key (used once, never stored)" }, "days": { "type": "integer", "title": "Days", "description": "How many days back to import (clamped to 1-90)", "default": 30 } }, "type": "object", "required": [ "api_key" ], "title": "OpenAICostImportRequest", "description": "Request to import retroactive costs from OpenAI's organization costs API" }, "OpenAICostImportResponse": { "properties": { "total_usd": { "type": "number", "title": "Total Usd" }, "days": { "items": { "$ref": "#/components/schemas/DailyCost" }, "type": "array", "title": "Days" } }, "type": "object", "required": [ "total_usd", "days" ], "title": "OpenAICostImportResponse", "description": "Aggregated daily costs from OpenAI" }, "OutcomeCreate": { "properties": { "trace_id": { "type": "string", "maxLength": 64, "minLength": 1, "title": "Trace Id" }, "workflow": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "Workflow" }, "success": { "type": "boolean", "title": "Success", "default": true }, "label": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "Label" } }, "type": "object", "required": [ "trace_id" ], "title": "OutcomeCreate", "description": "How one run ended, as reported by the SDK or an external control plane." }, "ParetoInfo": { "properties": { "top_count": { "type": "integer", "title": "Top Count" }, "top_share": { "type": "number", "title": "Top Share" }, "total_models": { "type": "integer", "title": "Total Models" } }, "type": "object", "required": [ "top_count", "top_share", "total_models" ], "title": "ParetoInfo", "description": "Cost concentration: how few models drive ≥80% of spend." }, "PasswordChangeRequest": { "properties": { "current_password": { "type": "string", "title": "Current Password", "description": "Current password" }, "new_password": { "type": "string", "maxLength": 100, "minLength": 8, "title": "New Password", "description": "New password" } }, "type": "object", "required": [ "current_password", "new_password" ], "title": "PasswordChangeRequest", "description": "Change password request (when logged in)" }, "PasswordResetConfirm": { "properties": { "token": { "type": "string", "title": "Token", "description": "Password reset token from email" }, "new_password": { "type": "string", "maxLength": 100, "minLength": 8, "title": "New Password", "description": "New password" } }, "type": "object", "required": [ "token", "new_password" ], "title": "PasswordResetConfirm", "description": "Confirm password reset with token" }, "PasswordResetRequest": { "properties": { "email": { "type": "string", "format": "email", "title": "Email", "description": "Email address for password reset" } }, "type": "object", "required": [ "email" ], "title": "PasswordResetRequest", "description": "Request password reset email" }, "PolicyCheckResponse": { "properties": { "policies_accepted": { "type": "boolean", "title": "Policies Accepted" }, "terms": { "$ref": "#/components/schemas/PolicyConsentStatus" }, "privacy": { "$ref": "#/components/schemas/PolicyConsentStatus" } }, "type": "object", "required": [ "policies_accepted", "terms", "privacy" ], "title": "PolicyCheckResponse", "description": "Response for policy version check" }, "PolicyConsentInput": { "properties": { "policy_type": { "type": "string", "title": "Policy Type", "description": "Policy type: 'terms' or 'privacy'" }, "policy_version": { "type": "string", "title": "Policy Version", "description": "Version accepted, e.g., '1.0'" } }, "type": "object", "required": [ "policy_type", "policy_version" ], "title": "PolicyConsentInput", "description": "Single policy consent record" }, "PolicyConsentStatus": { "properties": { "policy_type": { "type": "string", "title": "Policy Type" }, "current_version": { "type": "string", "title": "Current Version" }, "accepted_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Accepted Version" }, "accepted_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Accepted At" }, "is_current": { "type": "boolean", "title": "Is Current", "default": false } }, "type": "object", "required": [ "policy_type", "current_version" ], "title": "PolicyConsentStatus", "description": "Status of a user's policy consent" }, "PricingCatalogResponse": { "properties": { "pricing": { "additionalProperties": { "$ref": "#/components/schemas/PricingRates" }, "type": "object", "title": "Pricing", "description": "Model name -> rates. Keys are the names AgentCost bills against." }, "source": { "type": "string", "title": "Source", "description": "\"database\" for the synced catalogue, \"defaults\" for the built-in fallback set." }, "last_updated": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Updated", "description": "ISO-8601 timestamp of the last successful catalogue sync; null if never synced." } }, "type": "object", "required": [ "pricing", "source", "last_updated" ], "title": "PricingCatalogResponse", "description": "The full public model catalogue, keyed by model name." }, "PricingEntry": { "properties": { "input": { "anyOf": [ { "type": "number", "maximum": 10, "minimum": 0 }, { "type": "null" } ], "title": "Input" }, "output": { "anyOf": [ { "type": "number", "maximum": 10, "minimum": 0 }, { "type": "null" } ], "title": "Output" }, "provider": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ], "title": "Provider" } }, "additionalProperties": false, "type": "object", "title": "PricingEntry", "description": "One model's rates, in USD per 1,000 tokens." }, "PricingRates": { "properties": { "input": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Input", "description": "Cost per 1,000 input (prompt) tokens, USD." }, "output": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Output", "description": "Cost per 1,000 output (completion) tokens, USD." }, "cached_input": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Cached Input", "description": "Cost per 1,000 cached input tokens, USD. null means the provider publishes no cached rate -- bill cached tokens at the full input rate." }, "cache_write": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Cache Write", "description": "Cost per 1,000 tokens written to the prompt cache, USD. null if not published." }, "provider": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Provider", "description": "Provider slug, e.g. openai, anthropic, google." }, "mode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Mode", "description": "Model modality: chat, embedding, image_generation, audio_transcription, ..." }, "deprecation_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Deprecation Date", "description": "Upstream-announced retirement date, YYYY-MM-DD. null if none announced." }, "updated_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Updated At", "description": "ISO-8601 timestamp of when this model's price last changed." } }, "type": "object", "title": "PricingRates", "description": "One model's rates, in USD per 1,000 tokens." }, "PricingSyncStatusResponse": { "properties": { "status": { "type": "string", "title": "Status", "description": "\"synced\", \"partial\", or \"not_synced\"." }, "message": { "type": "string", "title": "Message", "description": "Human-readable summary of the same state." }, "total_models": { "type": "integer", "title": "Total Models", "description": "Active models currently in the catalogue." }, "fallback_models": { "type": "integer", "title": "Fallback Models", "description": "Size of the built-in fallback set used when the catalogue is empty." }, "last_updated": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Updated", "description": "ISO-8601 timestamp of the last successful sync." }, "models_by_provider": { "additionalProperties": { "type": "integer" }, "type": "object", "title": "Models By Provider", "description": "Active model count per provider." }, "models_by_source": { "additionalProperties": { "type": "integer" }, "type": "object", "title": "Models By Source", "description": "Active model count per upstream pricing source." }, "database_populated": { "type": "boolean", "title": "Database Populated", "description": "False when the fallback set is being served." }, "sync_endpoints": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Sync Endpoints", "description": "Admin-only endpoints that trigger a resync." } }, "type": "object", "required": [ "status", "message", "total_models", "fallback_models", "last_updated", "models_by_provider", "models_by_source", "database_populated", "sync_endpoints" ], "title": "PricingSyncStatusResponse", "description": "Freshness and composition of the catalogue." }, "ProfileUpdate": { "properties": { "name": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "Name" }, "avatar_url": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "null" } ], "title": "Avatar Url" } }, "type": "object", "title": "ProfileUpdate", "description": "Update user profile" }, "ProjectBudgetResponse": { "properties": { "project_id": { "type": "string", "title": "Project Id" }, "monthly_budget_usd": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Monthly Budget Usd" }, "budget_enforcement_mode": { "type": "string", "enum": [ "off", "warn", "hard_cap" ], "title": "Budget Enforcement Mode", "default": "off" }, "budget_alert_thresholds": { "items": { "type": "number" }, "type": "array", "title": "Budget Alert Thresholds" }, "current_month_spend": { "type": "number", "title": "Current Month Spend" }, "current_month_spend_usd": { "type": "number", "title": "Current Month Spend Usd", "default": 0 }, "utilization_percent": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Utilization Percent" }, "period_key": { "type": "string", "title": "Period Key" }, "budget_currency": { "type": "string", "enum": [ "USD", "INR" ], "title": "Budget Currency", "default": "USD" }, "fx_rate": { "type": "number", "title": "Fx Rate", "default": 1 } }, "type": "object", "required": [ "project_id", "budget_alert_thresholds", "current_month_spend", "period_key" ], "title": "ProjectBudgetResponse", "description": "Project budget settings with current utilization snapshot.\n\nAll monetary values are expressed in ``budget_currency``. The raw\nUSD-denominated spend (from event costs) is also returned for clients\nthat want to display it." }, "ProjectBudgetState": { "properties": { "project_id": { "type": "string", "title": "Project Id" }, "enabled": { "type": "boolean", "title": "Enabled" }, "mode": { "type": "string", "title": "Mode" }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Currency" }, "budget": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Budget" }, "spend_mtd": { "type": "number", "title": "Spend Mtd" }, "remaining": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Remaining" }, "utilization_percent": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Utilization Percent" }, "thresholds": { "items": { "type": "number" }, "type": "array", "title": "Thresholds" }, "thresholds_crossed": { "items": { "type": "number" }, "type": "array", "title": "Thresholds Crossed" }, "exhausted": { "type": "boolean", "title": "Exhausted" }, "period_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Period Key" }, "period_ends_at": { "type": "string", "title": "Period Ends At" }, "as_of": { "type": "string", "title": "As Of" } }, "type": "object", "required": [ "project_id", "enabled", "mode", "spend_mtd", "exhausted", "period_ends_at", "as_of" ], "title": "ProjectBudgetState", "description": "Compact budget position for machine consumers." }, "ProjectBudgetUpdate": { "properties": { "monthly_budget_usd": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ], "title": "Monthly Budget Usd" }, "budget_enforcement_mode": { "type": "string", "enum": [ "off", "warn", "hard_cap" ], "title": "Budget Enforcement Mode", "default": "warn" }, "budget_alert_thresholds": { "items": { "type": "number" }, "type": "array", "title": "Budget Alert Thresholds" }, "budget_currency": { "type": "string", "enum": [ "USD", "INR" ], "title": "Budget Currency", "default": "USD" } }, "type": "object", "title": "ProjectBudgetUpdate", "description": "Update project budget settings.\n\n``monthly_budget_usd`` accepts the budget amount in ``budget_currency``\n(the name is retained for backward compatibility with prior clients)." }, "ProjectCreate": { "properties": { "name": { "type": "string", "maxLength": 255, "minLength": 1, "title": "Name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" } }, "type": "object", "required": [ "name" ], "title": "ProjectCreate", "description": "Create project request" }, "ProjectResponse": { "properties": { "id": { "type": "string", "title": "Id" }, "name": { "type": "string", "title": "Name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "api_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Api Key" }, "key_prefix": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Key Prefix" }, "is_active": { "type": "boolean", "title": "Is Active" }, "monthly_budget_usd": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Monthly Budget Usd" }, "budget_enforcement_mode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Budget Enforcement Mode", "default": "off" }, "budget_alert_thresholds": { "anyOf": [ { "items": { "type": "number" }, "type": "array" }, { "type": "null" } ], "title": "Budget Alert Thresholds" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" } }, "type": "object", "required": [ "id", "name", "is_active", "created_at" ], "title": "ProjectResponse", "description": "Project response" }, "ProjectUpdate": { "properties": { "name": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "Name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "is_active": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Active" } }, "type": "object", "title": "ProjectUpdate", "description": "Update project request" }, "ProjectWebhookResponse": { "properties": { "project_id": { "type": "string", "title": "Project Id" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Url" }, "secret_set": { "type": "boolean", "title": "Secret Set", "default": false } }, "type": "object", "required": [ "project_id" ], "title": "ProjectWebhookResponse", "description": "Current webhook configuration. Never echoes the secret." }, "ProjectWebhookTestResponse": { "properties": { "delivered": { "type": "boolean", "title": "Delivered" }, "status_code": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Status Code" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" } }, "type": "object", "required": [ "delivered" ], "title": "ProjectWebhookTestResponse", "description": "Result of a test delivery to the configured webhook." }, "ProjectWebhookUpdate": { "properties": { "url": { "anyOf": [ { "type": "string", "maxLength": 2048 }, { "type": "null" } ], "title": "Url" }, "secret": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "title": "Secret" } }, "type": "object", "title": "ProjectWebhookUpdate", "description": "Configure signed push egress for budget events.\n\nSend ``url: null`` to disable; this also clears the stored secret. When\n``url`` is set, omitting ``secret`` keeps the existing one and an empty\nstring clears it. The secret is write-only — no endpoint returns it, only\nwhether one is set." }, "RecommendationFeedback": { "properties": { "feedback": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Feedback" } }, "type": "object", "title": "RecommendationFeedback" }, "RefreshTokenRequest": { "properties": { "refresh_token": { "type": "string", "title": "Refresh Token" } }, "type": "object", "required": [ "refresh_token" ], "title": "RefreshTokenRequest", "description": "Refresh token request" }, "RegisterResponse": { "properties": { "access_token": { "type": "string", "title": "Access Token" }, "refresh_token": { "type": "string", "title": "Refresh Token" }, "token_type": { "type": "string", "title": "Token Type", "default": "bearer" }, "expires_in": { "type": "integer", "title": "Expires In" }, "user": { "$ref": "#/components/schemas/UserResponse" }, "message": { "type": "string", "title": "Message", "default": "Registration successful. Please check your email to verify your account." }, "verification_email_sent": { "type": "boolean", "title": "Verification Email Sent", "default": false }, "default_project": { "anyOf": [ { "$ref": "#/components/schemas/DefaultProjectInfo" }, { "type": "null" } ] } }, "type": "object", "required": [ "access_token", "refresh_token", "expires_in", "user" ], "title": "RegisterResponse", "description": "Registration response - includes tokens so the user is logged in immediately" }, "RejectedEvent": { "properties": { "index": { "type": "integer", "title": "Index" }, "reason": { "type": "string", "title": "Reason" } }, "type": "object", "required": [ "index", "reason" ], "title": "RejectedEvent", "description": "An event that failed validation, echoed back so clients can fix it." }, "ReportSummary": { "properties": { "cost": { "$ref": "#/components/schemas/MetricDelta" }, "calls": { "$ref": "#/components/schemas/MetricDelta" }, "tokens": { "$ref": "#/components/schemas/MetricDelta" }, "success_rate": { "$ref": "#/components/schemas/MetricDelta" }, "avg_latency_ms": { "$ref": "#/components/schemas/MetricDelta" }, "blended_cost_per_1k": { "type": "number", "title": "Blended Cost Per 1K" }, "in_out_ratio": { "type": "number", "title": "In Out Ratio" } }, "type": "object", "required": [ "cost", "calls", "tokens", "success_rate", "avg_latency_ms", "blended_cost_per_1k", "in_out_ratio" ], "title": "ReportSummary", "description": "Executive-summary band: KPIs with period-over-period deltas." }, "ResendVerificationRequest": { "properties": { "email": { "type": "string", "format": "email", "title": "Email", "description": "Email address to resend verification" } }, "type": "object", "required": [ "email" ], "title": "ResendVerificationRequest", "description": "Resend verification email request" }, "RunRateProjection": { "properties": { "daily_avg_cost": { "type": "number", "title": "Daily Avg Cost" }, "projected_monthly_cost": { "type": "number", "title": "Projected Monthly Cost" }, "window_days": { "type": "number", "title": "Window Days" } }, "type": "object", "required": [ "daily_avg_cost", "projected_monthly_cost", "window_days" ], "title": "RunRateProjection" }, "SavingsRollup": { "properties": { "total_potential_savings_monthly": { "type": "number", "title": "Total Potential Savings Monthly", "default": 0 }, "total_potential_savings_percent": { "type": "number", "title": "Total Potential Savings Percent", "default": 0 }, "suggestion_count": { "type": "integer", "title": "Suggestion Count", "default": 0 }, "high_priority_count": { "type": "integer", "title": "High Priority Count", "default": 0 }, "top_suggestions": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Top Suggestions" } }, "type": "object", "title": "SavingsRollup" }, "SessionInfo": { "properties": { "id": { "type": "string", "title": "Id" }, "device_info": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Device Info" }, "ip_address": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Ip Address" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "last_used_at": { "type": "string", "format": "date-time", "title": "Last Used At" }, "expires_at": { "type": "string", "format": "date-time", "title": "Expires At" }, "is_current": { "type": "boolean", "title": "Is Current", "default": false } }, "type": "object", "required": [ "id", "created_at", "last_used_at", "expires_at" ], "title": "SessionInfo", "description": "Active session information" }, "SessionListResponse": { "properties": { "sessions": { "items": { "$ref": "#/components/schemas/SessionInfo" }, "type": "array", "title": "Sessions" }, "total": { "type": "integer", "title": "Total" } }, "type": "object", "required": [ "sessions", "total" ], "title": "SessionListResponse", "description": "List of active sessions" }, "TimeSeriesPoint": { "properties": { "timestamp": { "type": "string", "format": "date-time", "title": "Timestamp" }, "calls": { "type": "integer", "title": "Calls" }, "tokens": { "type": "integer", "title": "Tokens" }, "cost": { "type": "number", "title": "Cost" }, "avg_latency_ms": { "type": "number", "title": "Avg Latency Ms" } }, "type": "object", "required": [ "timestamp", "calls", "tokens", "cost", "avg_latency_ms" ], "title": "TimeSeriesPoint", "description": "Single point in time series" }, "TokenEfficiency": { "properties": { "blended_cost_per_1k": { "type": "number", "title": "Blended Cost Per 1K" }, "in_out_ratio": { "type": "number", "title": "In Out Ratio" }, "total_input_tokens": { "type": "integer", "title": "Total Input Tokens" }, "total_output_tokens": { "type": "integer", "title": "Total Output Tokens" }, "by_model": { "items": { "$ref": "#/components/schemas/ModelEfficiency" }, "type": "array", "title": "By Model" } }, "type": "object", "required": [ "blended_cost_per_1k", "in_out_ratio", "total_input_tokens", "total_output_tokens", "by_model" ], "title": "TokenEfficiency" }, "TokenResponse": { "properties": { "access_token": { "type": "string", "title": "Access Token" }, "refresh_token": { "type": "string", "title": "Refresh Token" }, "token_type": { "type": "string", "title": "Token Type", "default": "bearer" }, "expires_in": { "type": "integer", "title": "Expires In" }, "user": { "$ref": "#/components/schemas/UserResponse" }, "default_project": { "anyOf": [ { "$ref": "#/components/schemas/DefaultProjectInfo" }, { "type": "null" } ] } }, "type": "object", "required": [ "access_token", "refresh_token", "expires_in", "user" ], "title": "TokenResponse", "description": "JWT token response" }, "TopError": { "properties": { "error": { "type": "string", "title": "Error" }, "count": { "type": "integer", "title": "Count" } }, "type": "object", "required": [ "error", "count" ], "title": "TopError" }, "UpdateRoleRequest": { "properties": { "role": { "type": "string", "title": "Role", "description": "New role: admin, member, or viewer" } }, "type": "object", "required": [ "role" ], "title": "UpdateRoleRequest" }, "UsageCadence": { "properties": { "busiest_day": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Busiest Day" }, "busiest_hour": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Busiest Hour" }, "by_dow": { "items": { "$ref": "#/components/schemas/CadenceBucket" }, "type": "array", "title": "By Dow" }, "by_hour": { "items": { "$ref": "#/components/schemas/CadenceBucket" }, "type": "array", "title": "By Hour" } }, "type": "object", "required": [ "by_dow", "by_hour" ], "title": "UsageCadence" }, "UserLogin": { "properties": { "email": { "type": "string", "format": "email", "title": "Email", "description": "User email address" }, "password": { "type": "string", "title": "Password", "description": "Password" }, "remember_me": { "type": "boolean", "title": "Remember Me", "description": "Extended session duration", "default": false } }, "type": "object", "required": [ "email", "password" ], "title": "UserLogin", "description": "User login request" }, "UserRegister": { "properties": { "email": { "type": "string", "format": "email", "title": "Email", "description": "User email address" }, "password": { "type": "string", "maxLength": 100, "minLength": 8, "title": "Password", "description": "Password (min 8 chars)" }, "name": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "Name", "description": "Display name" }, "accept_terms": { "type": "boolean", "title": "Accept Terms", "description": "User accepts Terms of Service" }, "accept_privacy": { "type": "boolean", "title": "Accept Privacy", "description": "User accepts Privacy Policy" }, "terms_version": { "type": "string", "title": "Terms Version", "description": "Terms of Service version accepted" }, "privacy_version": { "type": "string", "title": "Privacy Version", "description": "Privacy Policy version accepted" } }, "type": "object", "required": [ "email", "password", "accept_terms", "accept_privacy", "terms_version", "privacy_version" ], "title": "UserRegister", "description": "User registration request" }, "UserResponse": { "properties": { "id": { "type": "string", "title": "Id" }, "email": { "type": "string", "title": "Email" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "avatar_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Avatar Url" }, "email_verified": { "type": "boolean", "title": "Email Verified" }, "is_active": { "type": "boolean", "title": "Is Active" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "last_login_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Login At" }, "auth_provider": { "type": "string", "title": "Auth Provider", "default": "email" }, "user_number": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "User Number" }, "milestone_badge": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Milestone Badge" } }, "type": "object", "required": [ "id", "email", "email_verified", "is_active", "created_at" ], "title": "UserResponse", "description": "User response (no password)" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "ApiError": { "type": "object", "title": "ApiError", "description": "The error envelope every AgentCost endpoint returns. `error.code` is stable and safe to branch on; `detail` repeats the message as a plain string for clients that read that field.", "required": [ "error", "detail" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "hint", "status" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable code, e.g. not_found, validation_error, rate_limited." }, "message": { "type": "string", "description": "What went wrong." }, "hint": { "type": "string", "description": "What to do about it." }, "status": { "type": "integer", "description": "The HTTP status, repeated in the body." }, "docs": { "type": "string", "format": "uri", "description": "Where the endpoint is documented." }, "fields": { "type": "array", "description": "Present on validation errors: the fields that failed and why.", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" }, "type": { "type": "string" } } } } } }, "detail": { "type": "string", "description": "The same message as a plain string." } } }, "EstimateRequest": { "type": "object", "title": "EstimateRequest", "required": [ "model", "input_tokens", "output_tokens" ], "properties": { "model": { "type": "string", "minLength": 1, "description": "Model name as the provider spells it, e.g. gpt-4o or claude-sonnet-4-6. Resolved against the catalogue exactly, then case-insensitively, then by provider-prefixed suffix." }, "input_tokens": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 100000000, "default": 0, "description": "Prompt tokens sent per call." }, "output_tokens": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 100000000, "default": 0, "description": "Completion tokens returned per call." }, "cached_input_tokens": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 100000000, "default": 0, "description": "Prompt tokens served from the provider's cache per call." }, "cache_write_tokens": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 100000000, "default": 0, "description": "Tokens written into the prompt cache per call." }, "calls": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 10000000, "default": 1, "description": "How many identical calls to price. Multiplies the per-call cost." } } }, "Estimate": { "type": "object", "title": "Estimate", "required": [ "model", "matched_to", "provider", "total_cost", "currency" ], "properties": { "model": { "type": "string", "description": "The model name as requested." }, "matched_to": { "type": "string", "description": "The catalogue entry it resolved to." }, "provider": { "type": "string", "description": "Provider slug for the matched entry." }, "calls": { "type": "integer", "description": "Number of calls priced." }, "tokens": { "type": "object", "description": "Token counts used, echoed back.", "properties": { "input": { "type": "integer" }, "output": { "type": "integer" }, "cached_input": { "type": "integer" }, "cache_write": { "type": "integer" }, "total": { "type": "integer" } } }, "rates_per_1k": { "type": "object", "description": "USD per 1,000 tokens. Null means the provider publishes no such rate.", "properties": { "input": { "type": "number" }, "output": { "type": "number" }, "cached_input": { "type": [ "number", "null" ] }, "cache_write": { "type": [ "number", "null" ] } } }, "cost_per_call": { "type": "object", "description": "USD cost of a single call, broken down.", "properties": { "input_cost": { "type": "number" }, "output_cost": { "type": "number" }, "cached_input_cost": { "type": "number" }, "cache_write_cost": { "type": "number" }, "total": { "type": "number" } } }, "total_cost": { "type": "number", "description": "cost_per_call.total multiplied by calls, in USD." }, "currency": { "type": "string", "enum": [ "USD" ] }, "cached_billed_at_input_rate": { "type": "boolean", "description": "True when cached tokens were billed at the full input rate because the provider publishes no cached rate." } } } }, "securitySchemes": { "HTTPBearer": { "type": "http", "scheme": "bearer" }, "APIKeyHeader": { "type": "apiKey", "in": "header", "name": "Authorization" } } }, "tags": [ { "name": "Pricing", "description": "Public model catalogue. Per-1k input/output/cached rates, provider, mode and announced retirement dates for every model AgentCost can bill. No credentials required -- this is the read surface SDKs and agents call." }, { "name": "Health", "description": "Liveness and version reporting. No credentials required." }, { "name": "Root", "description": "Service banner pointing at the docs and health endpoints." }, { "name": "Authentication", "description": "Account registration, sign-in, OAuth exchange, email verification, password reset and session management. Issues the bearer tokens the rest of the API uses." }, { "name": "Events", "description": "LLM call ingestion. Batched writes from the SDK, plus read-back of stored events. Authenticated with a project API key ('Authorization: Bearer sk_...')." }, { "name": "Analytics", "description": "Aggregated spend: overview totals, per-agent and per-dimension breakdowns, time series, cache savings, workflow and trace analysis." }, { "name": "Optimizations", "description": "Cost-reduction recommendations, model-swap baselines, caching opportunities and effectiveness tracking for recommendations already applied." }, { "name": "Projects", "description": "Project lifecycle, budgets, webhooks and API-key rotation." }, { "name": "Project Members", "description": "Team membership, roles and invitations on a project." }, { "name": "Feedback", "description": "Public feedback board: submissions, comments and upvotes." }, { "name": "Attachments", "description": "Upload limits and auth-gated attachment download." }, { "name": "Notifications", "description": "In-app notification feed and read state." }, { "name": "Currency", "description": "USD conversion rates for non-USD cost display." }, { "name": "Integrations", "description": "Provider-side cost import from OpenAI and Anthropic billing APIs." }, { "name": "Metrics", "description": "Prometheus exposition of per-project ingestion and spend metrics." }, { "name": "Admin", "description": "Superuser-only operations. Not part of the public contract." }, { "name": "Demo", "description": "Anonymous demo-mode telemetry. No PII." } ] }