exchangerate-dev Account API

openapi: 3.2.0
info:
  title: exchangerate.dev Account API
  description: 'Live indicative foreign-exchange rates for developers. Explicit `source` and `market_session` labels on every response — live intraday (~60s) on trading days for all currencies, with ECB daily fallback in the 144-currency catalog (10296 unique pairs). Free tier: 5,000 calls/month, no card. Live rates 15 minutes delayed. MCP server: https://api.exchangerate.dev/v1/mcp/ · Docs: https://exchangerate.dev/docs'
  contact:
    url: https://exchangerate.dev/docs
  version: '1.0'
tags:
- name: Account
paths:
  /v1/account/provision:
    post:
      summary: Provision
      description: 'Idempotent onboarding: create org if absent; issue first key if absent. Plaintext is

        also re-revealable later via GET /v1/account (at-rest encrypted; dashboard full-key copy).'
      operationId: provision_v1_account_provision_post
      requestBody:
        content:
          application/json:
            schema:
              anyOf:
              - $ref: '#/components/schemas/ProvisionRequest'
              - type: 'null'
              title: Body
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKeyCreatedResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Account
  /v1/account/checkout:
    post:
      summary: Account Checkout
      description: Open the selected safe billing action for the API key's organization.
      operationId: account_checkout_v1_account_checkout_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CheckoutRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckoutResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Account
  /v1/account/checkout-session:
    post:
      summary: Account Checkout Session
      description: 'Website checkout: ownership comes exclusively from the verified login.'
      operationId: account_checkout_session_v1_account_checkout_session_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CheckoutRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckoutResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Account
  /v1/account:
    get:
      summary: Account
      description: 'Read-only account summary: org, active key, monthly usage.'
      operationId: account_v1_account_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountResponse'
      tags:
      - Account
    delete:
      summary: Delete Account
      description: 'Self-serve account deletion.


        Cancels the Stripe subscription immediately (if present), then purges all org data

        in one transaction: usage_daily → usage_monthly → api_keys → organizations.

        Does NOT delete auth.users — the web BFF does that with the service role.

        Does NOT touch webhook_events (global Stripe idempotency table).


        Abort policy: if Stripe cancel fails for any reason other than "already gone",

        returns 502 and deletes NOTHING (never orphan an active subscription).'
      operationId: delete_account_v1_account_delete
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteAccountResponse'
      tags:
      - Account
  /v1/account/usage/daily:
    get:
      summary: Account Usage Daily
      description: 'Dashboard only: requires the signed-in dashboard session token, not an API key. API keys get 401 invalid_session_token. Zero-filled daily served requests and rate-limited hits for the signed-in account.'
      operationId: account_usage_daily_v1_account_usage_daily_get
      parameters:
      - name: days
        in: query
        required: false
        schema:
          type: integer
          maximum: 90
          minimum: 1
          default: 30
          title: Days
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DailyUsageResponse'
        '401':
          description: 'Authentication failed: invalid_api_key (or invalid_session_token on dashboard routes).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: 'no_account: the signed-in user has no organization yet.'
        '503':
          description: 'auth_unavailable: the session could not be verified; retry.'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Account
  /v1/account/keys:
    get:
      summary: List Named Keys
      operationId: list_named_keys_v1_account_keys_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response List Named Keys V1 Account Keys Get
      tags:
      - Account
    post:
      summary: Manage Named Key
      operationId: manage_named_key_v1_account_keys_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NamedKeyRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Manage Named Key V1 Account Keys Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Account
components:
  schemas:
    NamedKeyRequest:
      properties:
        action:
          type: string
          enum:
          - create
          - rename
          - rotate
          - revoke
          title: Action
        id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Id
        request_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Request Id
        name:
          anyOf:
          - type: string
            maxLength: 64
          - type: 'null'
          title: Name
      additionalProperties: false
      type: object
      required:
      - action
      title: NamedKeyRequest
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    AccountResponse:
      properties:
        result:
          type: string
          title: Result
          default: success
        email:
          anyOf:
          - type: string
          - type: 'null'
          title: Email
        org:
          anyOf:
          - $ref: '#/components/schemas/OrgSummary'
          - type: 'null'
        key:
          anyOf:
          - $ref: '#/components/schemas/KeySummary'
          - type: 'null'
        keys:
          items:
            $ref: '#/components/schemas/KeyInventorySummary'
          type: array
          title: Keys
        usage:
          anyOf:
          - $ref: '#/components/schemas/UsageSummary'
          - type: 'null'
        billing:
          anyOf:
          - $ref: '#/components/schemas/BillingSummary'
          - type: 'null'
      type: object
      required:
      - email
      - org
      - key
      - usage
      title: AccountResponse
    UsageSummary:
      properties:
        calls_this_month:
          type: integer
          title: Calls This Month
        limit:
          type: integer
          title: Limit
        resets_on:
          type: string
          title: Resets On
      type: object
      required:
      - calls_this_month
      - limit
      - resets_on
      title: UsageSummary
    CheckoutRequest:
      properties:
        plan:
          type: string
          enum:
          - basic_2026
          - plus_2026
          - pro_2026
          title: Plan
        interval:
          type: string
          pattern: ^(monthly|yearly)$
          title: Interval
          default: monthly
      additionalProperties: false
      type: object
      required:
      - plan
      title: CheckoutRequest
      description: Selected paid plan; account identity comes from verified server-side auth.
    ApiKeyCreatedResponse:
      properties:
        result:
          type: string
          title: Result
          default: success
        created:
          type: boolean
          title: Created
        org_id:
          type: string
          title: Org Id
        plaintext:
          anyOf:
          - type: string
          - type: 'null'
          title: Plaintext
        key:
          anyOf:
          - $ref: '#/components/schemas/KeySummary'
          - type: 'null'
      type: object
      required:
      - created
      - org_id
      - plaintext
      - key
      title: ApiKeyCreatedResponse
    ErrorResponse:
      properties:
        result:
          type: string
          title: Result
          default: error
        code:
          type: string
          title: Code
        message:
          type: string
          title: Message
      type: object
      required:
      - code
      - message
      title: ErrorResponse
    DailyUsageResponse:
      properties:
        result:
          type: string
          title: Result
          default: success
        tier:
          type: string
          title: Tier
        limit:
          type: integer
          title: Limit
        month_to_date:
          type: integer
          title: Month To Date
        rate_limited_total:
          type: integer
          title: Rate Limited Total
        active_streams:
          anyOf:
          - type: integer
          - type: 'null'
          title: Active Streams
        max_streams:
          type: integer
          title: Max Streams
        days:
          items:
            $ref: '#/components/schemas/DailyUsageEntry'
          type: array
          title: Days
      type: object
      required:
      - tier
      - limit
      - month_to_date
      - rate_limited_total
      - max_streams
      - days
      title: DailyUsageResponse
    BillingSummary:
      properties:
        state:
          type: string
          enum:
          - none
          - pending
          - active
          - ending
          - failed
          - unpaid
          - ended
          - complimentary
          title: State
        interval:
          anyOf:
          - type: string
            enum:
            - monthly
            - yearly
          - type: 'null'
          title: Interval
        current_period_end:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Current Period End
        ends_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Ends At
      type: object
      required:
      - state
      title: BillingSummary
      description: The account's billing state (docs/BILLING-STATES.md); every screen reads this.
    KeyInventorySummary:
      properties:
        id:
          type: string
          title: Id
        prefix:
          type: string
          title: Prefix
        created_at:
          type: string
          title: Created At
        last_used_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Used At
        revoked_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Revoked At
      type: object
      required:
      - id
      - prefix
      - created_at
      title: KeyInventorySummary
    ProvisionRequest:
      properties:
        defer_key:
          type: boolean
          title: Defer Key
          default: false
        signup_attribution:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Signup Attribution
        marketing_consent:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Marketing Consent
      additionalProperties: false
      type: object
      title: ProvisionRequest
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    DailyUsageEntry:
      properties:
        date:
          type: string
          title: Date
        count:
          type: integer
          title: Count
        rate_limited:
          type: integer
          title: Rate Limited
      type: object
      required:
      - date
      - count
      - rate_limited
      title: DailyUsageEntry
    OrgSummary:
      properties:
        id:
          type: string
          title: Id
        tier:
          type: string
          title: Tier
        status:
          type: string
          title: Status
        stream_connections:
          type: integer
          title: Stream Connections
          default: 0
        stream_pairs_per_connection:
          type: integer
          title: Stream Pairs Per Connection
          default: 0
      type: object
      required:
      - id
      - tier
      - status
      title: OrgSummary
    DeleteAccountResponse:
      properties:
        result:
          type: string
          title: Result
          default: success
        deleted:
          type: boolean
          title: Deleted
          default: true
      type: object
      title: DeleteAccountResponse
    KeySummary:
      properties:
        first_success_at:
          anyOf:
          - type: string
          - type: 'null'
          title: First Success At
        prefix:
          type: string
          title: Prefix
        plaintext:
          anyOf:
          - type: string
          - type: 'null'
          title: Plaintext
        created_at:
          type: string
          title: Created At
        last_used_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Used At
      type: object
      required:
      - prefix
      - created_at
      title: KeySummary
    CheckoutResponse:
      properties:
        result:
          type: string
          title: Result
          default: success
        action:
          type: string
          pattern: ^(checkout|manage_subscription)$
          title: Action
        url:
          type: string
          title: Url
        expires_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Expires At
      type: object
      required:
      - action
      - url
      title: CheckoutResponse