FastAF Account API

openapi: 3.2.0
info:
  title: FastAF Account API
  version: v1
  contact:
    email: support@fastaf.co
    url: https://fastaf.co/docs/#x402
  description: 'FastAF is a web data API for AI agents: Google SERP, Maps, ecommerce, web scraping, AI extraction, screenshots, news, jobs, research, public profiles and video transcripts. Use prepaid API keys or account-free x402 v2 payments.'
  x-guidance: 'Use GET /x402/v1/{endpoint} with query parameters (not POST or a JSON body). Choose serp for Google search, maps for places, news/shopping/scholar/jobs for specialized search, ai for Google AI Mode, amazon/youtube for their resource variants, linkedin/x for public profiles, walmart/zillow/ebay for structured commerce or listings, scrape for public HTML or markdown, and screenshot for images. Use the dedicated zillow and ebay endpoints instead of scrape for those sites. The q and lang aliases are accepted for query (search_query on YouTube) and language. Send a valid unpaid request first; read the x402 v2 PAYMENT-REQUIRED header, sign with an x402 client such as @x402/fetch, and retry the identical URL with PAYMENT-SIGNATURE. USDC payment uses the network and amount in that live challenge; no API-key authentication is needed. Only successful results are settled; inspect PAYMENT-RESPONSE for the receipt. Prices here are decimal USD, while the challenge uses USDC atomic units (six decimals). Dynamic prices depend on advance_search (serp), resource (amazon/youtube), or rendering, proxies/country and AI extraction (scrape). Scrape site defaults, including Booking rendering and Reddit feed mode, are applied before quoting. A bare unsigned URL returns a default-variant discovery quote only: add valid parameters and request a new challenge before paying. Unpaid HEAD probes also return PAYMENT-REQUIRED with no body; use GET, not HEAD, to pay for data. Invalid parameterized requests and blocked targets return 400; payment headers never bypass validation. Never reuse a settled signature for a new call. Respect Retry-After on rate/capacity errors. For the separate prepaid-key API and authenticated credit-pack top-up, see /v1/openapi.json. Get a free API key at https://fastaf.co/signup/ with an email address, terms acceptance and browser verification. No card is required. POST /public/signup sends an email confirmation link and sets a dashboard session cookie; it does not return an API key. Follow the emailed GET /public/signin/{token} link, then create a key in the dashboard (POST /v1/keys with the session cookie). The key is shown only once. Email confirmation unlocks 2 free calls per account in total, not per day, shared across all keys and all offered REST/MCP endpoints, valid for 12 months; failed calls restore their slot. Unverified trial accounts receive email_verification_required (403) before any data call or trial reservation. Signups are limited per IPv4 /24 or IPv6 /64 network per UTC day (default 3); 429 means retry after the reset. GET /v1/usage reports free_requests_remaining separately from balance_credits. POST /v1/signup is retired and always returns 410 signup_disabled. Agents without an inbox can use /x402/v1/{endpoint} without an account.'
  x-signup-guidance: Get a free API key at https://fastaf.co/signup/ with an email address, terms acceptance and browser verification. No card is required. POST /public/signup sends an email confirmation link and sets a dashboard session cookie; it does not return an API key. Follow the emailed GET /public/signin/{token} link, then create a key in the dashboard (POST /v1/keys with the session cookie). The key is shown only once. Email confirmation unlocks 2 free calls per account in total, not per day, shared across all keys and all offered REST/MCP endpoints, valid for 12 months; failed calls restore their slot. Unverified trial accounts receive email_verification_required (403) before any data call or trial reservation. Signups are limited per IPv4 /24 or IPv6 /64 network per UTC day (default 3); 429 means retry after the reset. GET /v1/usage reports free_requests_remaining separately from balance_credits. POST /v1/signup is retired and always returns 410 signup_disabled. Agents without an inbox can use /x402/v1/{endpoint} without an account.
servers:
- url: https://api.fastaf.co
tags:
- name: Account
paths:
  /v1/usage:
    get:
      tags:
      - Account
      summary: Current account usage and credit balance
      operationId: getUsage
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Usage snapshot.
          content:
            application/json:
              schema:
                type: object
                required:
                - balance_credits
                - free_requests_remaining
                - lifetime_usage_credits
                - concurrency_limit
                - active_requests
                properties:
                  balance_credits:
                    type: integer
                    minimum: 0
                  free_requests_remaining:
                    type: integer
                    minimum: 0
                    maximum: 2
                    description: Unreserved trial requests remaining; separate from credits.
                  lifetime_usage_credits:
                    type: integer
                    minimum: 0
                  concurrency_limit:
                    type: integer
                    minimum: 1
                  active_requests:
                    type: integer
                    minimum: 0
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /v1/requests:
    get:
      tags:
      - Account
      summary: Recent API requests for the current account
      description: Per-request log entries from the last 30 days, newest first, with cursor pagination.
      operationId: listRequests
      security:
      - bearerAuth: []
      parameters:
      - name: limit
        in: query
        required: false
        description: Page size. Defaults to 50.
        schema:
          type: integer
          minimum: 1
          maximum: 100
      - name: before
        in: query
        required: false
        description: 'Cursor: return entries created strictly before this timestamp. Use next_before from the previous page.'
        schema:
          type: string
          format: date-time
      - name: before_id
        in: query
        required: false
        description: 'Cursor tiebreak: with before, also return entries at that same timestamp whose id sorts below this one. Use next_before_id from the previous page.'
        schema:
          type: string
      responses:
        '200':
          description: Request log page, newest first.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                - requests
                properties:
                  requests:
                    type: array
                    items:
                      $ref: '#/components/schemas/RequestLogEntry'
                  next_before:
                    type: string
                    format: date-time
                    description: Present when more entries exist; pass it as before to fetch the next page.
                  next_before_id:
                    type: string
                    description: Present with next_before; pass it as before_id so entries sharing that timestamp are not skipped.
        '400':
          description: The limit or before parameter is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /v1/usage/daily:
    get:
      tags:
      - Account
      summary: Daily usage aggregates per endpoint
      description: Credits, request counts and failures grouped by calendar day (UTC) and endpoint, for up to the last 90 days.
      operationId: getDailyUsage
      security:
      - bearerAuth: []
      parameters:
      - name: days
        in: query
        required: false
        description: Window size in days, inclusive of today. Defaults to 30.
        schema:
          type: integer
          minimum: 1
          maximum: 90
      responses:
        '200':
          description: Daily aggregates, newest day first.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                - days
                properties:
                  days:
                    type: array
                    items:
                      $ref: '#/components/schemas/UsageDay'
        '400':
          description: The days parameter is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /v1/keys:
    get:
      tags:
      - Account
      summary: List API keys for the current account
      operationId: listApiKeys
      security:
      - bearerAuth: []
      - sessionCookie: []
      responses:
        '200':
          description: API keys ordered by creation time, newest first.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                - keys
                properties:
                  keys:
                    type: array
                    items:
                      $ref: '#/components/schemas/ApiKey'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    post:
      tags:
      - Account
      summary: Create an API key for the current account
      description: At most five active keys are allowed. The full key is returned only in this response.
      operationId: createApiKey
      security:
      - bearerAuth: []
      - sessionCookie: []
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 100
                  pattern: .*\S.*
                  default: default
      responses:
        '201':
          description: API key created. The full key is shown only once.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatedApiKey'
        '400':
          description: The JSON body or key name is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          description: The account already has five active API keys.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /v1/keys/{id}:
    delete:
      tags:
      - Account
      summary: Revoke an API key
      description: The current key and the last active key on an account cannot be revoked.
      operationId: revokeApiKey
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: API key revoked.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                - revoked
                properties:
                  revoked:
                    type: boolean
                    const: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: The API key does not exist on this account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: The API key is the current key or the account's last active key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /v1/checkout:
    post:
      tags:
      - Account
      summary: Start a credit pack purchase with the API key
      description: Returns a payment link for the pack. The credits are added to the key's account when the payment is confirmed; check GET /v1/usage.
      operationId: createCheckout
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
              - pack
              properties:
                pack:
                  type: string
                  enum:
                  - starter
                  - growth
                  - scale
                  - pro
                  - business
      responses:
        '201':
          description: Payment link.
          content:
            application/json:
              schema:
                type: object
                required:
                - url
                properties:
                  url:
                    type: string
                    format: uri
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
components:
  responses:
    InternalServerError:
      description: The request failed unexpectedly.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    TooManyRequests:
      description: A rate or concurrency limit was reached.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Invalid request or parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: The account is suspended or email verification is required before data calls.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: A valid bearer API key is required.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ServiceUnavailable:
      description: The service is temporarily unavailable.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    UsageDay:
      type: object
      additionalProperties: false
      required:
      - day
      - endpoint
      - requests
      - credits
      - failed_requests
      properties:
        day:
          type: string
          format: date
        endpoint:
          type: string
          enum:
          - serp
          - maps
          - amazon
          - linkedin
          - youtube
          - scrape
          - news
          - shopping
          - scholar
          - jobs
          - ai
          - walmart
          - zillow
          - ebay
          - x
          - screenshot
        requests:
          type: integer
          minimum: 0
        credits:
          type: integer
          minimum: 0
        failed_requests:
          type: integer
          minimum: 0
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
            message:
              type: string
    RequestLogEntry:
      type: object
      additionalProperties: false
      required:
      - id
      - endpoint
      - status
      - credits
      - duration_ms
      - created_at
      properties:
        id:
          type: string
        endpoint:
          type: string
          enum:
          - serp
          - maps
          - amazon
          - linkedin
          - youtube
          - scrape
          - news
          - shopping
          - scholar
          - jobs
          - ai
          - walmart
          - zillow
          - ebay
          - x
          - screenshot
        status:
          type: integer
        credits:
          type: integer
          minimum: 0
        duration_ms:
          type: integer
          minimum: 0
        created_at:
          type: string
          format: date-time
    CreatedApiKey:
      type: object
      additionalProperties: false
      required:
      - id
      - prefix
      - name
      - status
      - created_at
      - last_used_at
      - key
      - warning
      properties:
        id:
          type: string
        prefix:
          type: string
          pattern: ^faf_live_
        name:
          type: string
          maxLength: 100
        status:
          type: string
          const: active
        created_at:
          type: string
        last_used_at:
          type: 'null'
        key:
          type: string
          pattern: ^faf_live_[0-9A-Za-z]{32}$
        warning:
          type: string
    ApiKey:
      type: object
      additionalProperties: false
      required:
      - id
      - prefix
      - name
      - status
      - created_at
      - last_used_at
      properties:
        id:
          type: string
        prefix:
          type: string
          pattern: ^faf_live_
        name:
          type: string
          maxLength: 100
        status:
          type: string
          enum:
          - active
          - revoked
        created_at:
          type: string
        last_used_at:
          type:
          - string
          - 'null'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
    sessionCookie:
      type: apiKey
      in: cookie
      name: fastaf_session