> ## Documentation Index > Fetch the complete documentation index at: https://phaseo.app/docs/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Phaseo Gateway base URL: https://api.phaseo.app/v1. Send `Authorization: Bearer $PHASEO_API_KEY` with every request. > Model IDs look like `provider/model`, for example `openai/gpt-6-astra`. Do not guess IDs: list them with `GET /v1/models` or check https://phaseo.app/models. `phaseo/free` routes to an available free model and needs no wallet balance. > For new text integrations prefer `POST /v1/responses`. `POST /v1/chat/completions` (OpenAI format) and `POST /v1/messages` (Anthropic format) suit existing code. > The full API contract is https://phaseo.app/docs/openapi/v1/openapi.yaml. Official SDKs: `@phaseo/sdk` (TypeScript) and `phaseo` (Python), plus Go, C#, PHP, Ruby and Rust. > Search these docs over MCP at https://phaseo.app/docs/mcp, and install Phaseo skills with `npx skills add https://phaseo.app/docs`. If a page is wrong or out of date, report it with the MCP `submit_feedback` tool. > Manage Phaseo accounts with the `phaseo` CLI (`npm install -g @phaseo/cli`, then `phaseo login` or `phaseo login --device-code`), the `/v1` Management API or the MCP server at `https://mcp.phaseo.app/mcp?access=manage`. Do not send users to the dashboard for account tasks. A person is still needed for sign-up, approving a sign-in, paying the first top-up on the checkout link that `phaseo credits add` returns when no card is saved, confirming each saved-card top-up from the emailed link, and account security (password, MFA, passkeys). Create API keys with `phaseo keys create --name --json`; never guess one. Credit top-ups need `phaseo login --scopes billing:write` first. Task map: https://phaseo.app/docs/v1/developers/manage-from-an-agent.md. # Update notification settings > Updates one or more durable notification-policy sections. Enabling auto top-up requires an existing saved payment method identifier and verified two-factor authentication. An existing auto top-up configuration may be updated without repeating the MFA acknowledgement. To enable auto top-up without MFA, clients must explicitly set `mfa_bypass_acknowledged` to true and provide the exact `mfa_bypass_phrase` value `I ACCEPT THE RISK`; payment collection remains an interactive account flow. > [!NOTE] > > Workspace notification administration requires an owner or admin identity and the matching settings scope. Destination targets are encrypted and never returned. ## OpenAPI ````yaml openapi/v1/openapi.yaml PATCH /notifications/settings openapi: 3.0.3 info: title: Phaseo Gateway API description: >- A gateway API for accessing various AI models with OpenAI-compatible endpoints. version: 1.0.0 contact: name: Phaseo url: https://phaseo.app email: danielbutler500@gmail.com servers: - url: https://api.phaseo.app/v1 description: Global routing security: - BearerAuth: [] tags: - name: Gateway description: Core Phaseo Gateway operations. paths: /notifications/settings: patch: tags: - Gateway summary: Update workspace notification settings description: >- Updates one or more durable notification-policy sections. Enabling auto top-up requires an existing saved payment method identifier and verified two-factor authentication. An existing auto top-up configuration may be updated without repeating the MFA acknowledgement. To enable auto top-up without MFA, clients must explicitly set `mfa_bypass_acknowledged` to true and provide the exact `mfa_bypass_phrase` value `I ACCEPT THE RISK`; payment collection remains an interactive account flow. operationId: updateWorkspaceNotificationSettings requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WorkspaceNotificationSettingsUpdateRequest' responses: '200': description: Notification settings updated content: application/json: schema: $ref: '#/components/schemas/WorkspaceNotificationSettingsResponse' default: description: Request failed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: [] components: schemas: WorkspaceNotificationSettingsUpdateRequest: type: object minProperties: 1 properties: auto_top_up: $ref: '#/components/schemas/WorkspaceAutoTopUpUpdate' low_balance_email: $ref: '#/components/schemas/WorkspaceLowBalanceEmailUpdate' email_preferences: $ref: '#/components/schemas/WorkspaceNotificationEmailPreferencesUpdate' spend: $ref: '#/components/schemas/WorkspaceSpendSettingsUpdate' additionalProperties: false WorkspaceNotificationSettingsResponse: type: object required: - data properties: data: $ref: '#/components/schemas/WorkspaceNotificationSettings' additionalProperties: false ErrorResponse: type: object required: - error properties: ok: type: boolean example: false error: description: >- The error object (`code`, `message`, `type`, `param` and optional `metadata`) that OpenAI-compatible SDKs read. Earlier responses returned the code string here; it is now also returned as top-level `code`. oneOf: - type: string - $ref: '#/components/schemas/ErrorObject' example: code: validation_error message: 'Unknown parameter: foo' type: invalid_request_error param: foo code: type: string description: The error code, the same value as `error.code`. example: validation_error message: type: string example: Human-readable error message description: type: string example: Additional error details. generation_id: type: string example: G-abc123 status_code: type: integer example: 502 error_type: type: string enum: - user - system example: system error_origin: type: string enum: - user - gateway - upstream example: upstream reason: type: string example: all_candidates_failed attempt_count: type: integer example: 2 failed_providers: type: array items: type: string example: - google-ai-studio - openai failed_statuses: type: array items: type: integer example: - 403 - 429 upstream_error: $ref: '#/components/schemas/ErrorUpstreamError' failure_sample: type: array items: $ref: '#/components/schemas/ErrorFailureSampleItem' provider_failure_diagnostics: $ref: '#/components/schemas/ErrorProviderFailureDiagnostics' routing_diagnostics: $ref: '#/components/schemas/ErrorRoutingDiagnostics' provider_candidate_diagnostics: $ref: '#/components/schemas/ErrorProviderCandidateDiagnostics' provider_enablement: $ref: '#/components/schemas/ErrorProviderEnablementDiagnostics' missing_pricing_providers: type: array items: type: string provider_payment_required_provider: type: string example: openai provider_payment_required_support_notice: type: string example: >- Our upstream provider billing appears to be unavailable. If this persists, contact support. details: type: array items: type: object additionalProperties: true additionalProperties: true WorkspaceAutoTopUpUpdate: type: object required: - enabled properties: enabled: type: boolean balance_threshold_nanos: type: integer minimum: 0 amount_nanos: type: integer minimum: 0 payment_method_id: type: string nullable: true mfa_bypass_acknowledged: type: boolean mfa_bypass_phrase: type: string additionalProperties: false WorkspaceLowBalanceEmailUpdate: type: object required: - enabled properties: enabled: type: boolean threshold_usd: type: number minimum: 0 multipleOf: 0.01 additionalProperties: false WorkspaceNotificationEmailPreferencesUpdate: type: object minProperties: 1 properties: auto_top_up_failure: type: boolean payment_method_expiring: type: boolean model_deprecation: type: boolean additionalProperties: false WorkspaceSpendSettingsUpdate: type: object minProperties: 1 properties: department_attribution: $ref: '#/components/schemas/WorkspaceSpendAttribution' billing_time_zone: $ref: '#/components/schemas/WorkspaceBillingTimeZone' report_cadence: $ref: '#/components/schemas/WorkspaceSpendReportCadence' report_include_admins: $ref: '#/components/schemas/WorkspaceSpendReportIncludeAdmins' additionalProperties: false WorkspaceNotificationSettings: type: object required: - auto_top_up - low_balance_email - email_preferences - spend properties: auto_top_up: $ref: '#/components/schemas/WorkspaceAutoTopUpSettings' low_balance_email: $ref: '#/components/schemas/WorkspaceLowBalanceEmailSettings' email_preferences: $ref: '#/components/schemas/WorkspaceNotificationEmailPreferences' spend: $ref: '#/components/schemas/WorkspaceSpendSettings' additionalProperties: false ErrorObject: type: object description: >- A gateway error in the shape OpenAI's SDKs read. `type` is set from the HTTP status: invalid_request_error for most 4xx, authentication_error (401), insufficient_quota (402), permission_error (403), not_found_error (404), rate_limit_error (429), service_unavailable (503), overloaded (529) and server_error for other 5xx. required: - code - message - type properties: code: type: string description: Machine-readable error code. example: validation_error message: type: string description: Human-readable explanation of the failure. example: 'Unknown parameter: foo' type: type: string description: The error type, following OpenAI's documented error types. enum: - invalid_request_error - authentication_error - permission_error - not_found_error - rate_limit_error - insufficient_quota - server_error - service_unavailable - overloaded example: invalid_request_error param: type: string nullable: true description: The request parameter that caused the error, when known. example: foo metadata: type: object description: >- Structured detail also returned at the top level, such as the failing provider, `reason`, `failed_statuses`, `retry_after_seconds` or `upstream_error`. additionalProperties: true additionalProperties: true ErrorUpstreamError: type: object properties: code: type: string nullable: true example: PERMISSION_DENIED message: type: string nullable: true example: The caller does not have permission. description: type: string nullable: true param: type: string nullable: true ErrorFailureSampleItem: type: object properties: provider: type: string nullable: true type: type: string nullable: true status: type: integer nullable: true upstream_error_code: type: string nullable: true upstream_error_message: type: string nullable: true upstream_error_description: type: string nullable: true upstream_error_param: type: string nullable: true upstream_payload_preview: type: string nullable: true retryable: type: boolean nullable: true additionalProperties: true ErrorProviderFailureDiagnostics: type: object properties: category: type: string enum: - credentials_not_configured - credentials_invalid_or_forbidden - provider_access_missing - region_or_project_restriction - model_unavailable_for_endpoint - rate_limited - server_error hint: type: string provider: type: string nullable: true ErrorRoutingDiagnostics: type: object properties: filterStages: type: array items: type: object properties: stage: type: string beforeCount: type: integer afterCount: type: integer droppedProviders: type: array items: type: object properties: providerId: type: string nullable: true reason: type: string nullable: true additionalProperties: true additionalProperties: true additionalProperties: true ErrorProviderCandidateDiagnostics: type: object properties: totalProviders: type: integer supportsEndpointCount: type: integer candidateCount: type: integer droppedUnsupportedEndpoint: type: array items: type: string droppedMissingAdapter: type: array items: type: object properties: providerId: type: string nullable: true endpoint: type: string nullable: true additionalProperties: true additionalProperties: true ErrorProviderEnablementDiagnostics: type: object properties: capability: type: string providersBefore: type: array items: type: string providersAfter: type: array items: type: string dropped: type: array items: type: object properties: providerId: type: string nullable: true reason: type: string nullable: true additionalProperties: true additionalProperties: true WorkspaceSpendAttribution: type: string description: >- How spend rules count a person's spend toward departments when their key has no department of its own: all counts it toward every department they belong to; primary counts it toward their primary department only. A key's own department always wins. enum: - all - primary WorkspaceBillingTimeZone: type: string maxLength: 64 description: >- IANA time zone for the calendar periods of spend rules that have no time zone of their own, and for spend reports. Defaults to UTC. Enforced key limits and workspace budgets always use UTC. example: Europe/London WorkspaceSpendReportCadence: type: string description: >- How often workspace owners get a spend report email, and admins too when report_include_admins is on: off, daily (09:00 for the day before), weekly (Monday 09:00 for the previous Monday-to-Sunday week) or monthly (the 1st at 09:00 for the previous month), in the billing time zone. Periods without spend are skipped. Workspace spend_report routes get one summary per report. Defaults to weekly. enum: - 'off' - daily - weekly - monthly WorkspaceSpendReportIncludeAdmins: type: boolean description: >- Also email the spend report to workspace admins, not only owners. Defaults to false. Anyone can unsubscribe from the link in the email. WorkspaceAutoTopUpSettings: type: object required: - enabled - balance_threshold_nanos - amount_nanos - payment_method_id properties: enabled: type: boolean balance_threshold_nanos: type: integer minimum: 0 amount_nanos: type: integer minimum: 0 payment_method_id: type: string nullable: true additionalProperties: false WorkspaceLowBalanceEmailSettings: type: object required: - enabled - threshold_usd properties: enabled: type: boolean threshold_usd: type: number minimum: 0 multipleOf: 0.01 additionalProperties: false WorkspaceNotificationEmailPreferences: type: object required: - auto_top_up_failure - payment_method_expiring - model_deprecation properties: auto_top_up_failure: type: boolean payment_method_expiring: type: boolean model_deprecation: type: boolean additionalProperties: false WorkspaceSpendSettings: type: object required: - department_attribution - billing_time_zone - report_cadence - report_include_admins properties: department_attribution: $ref: '#/components/schemas/WorkspaceSpendAttribution' billing_time_zone: $ref: '#/components/schemas/WorkspaceBillingTimeZone' report_cadence: $ref: '#/components/schemas/WorkspaceSpendReportCadence' report_include_admins: $ref: '#/components/schemas/WorkspaceSpendReportIncludeAdmins' additionalProperties: false securitySchemes: BearerAuth: type: http scheme: bearer description: Bearer token authentication ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.