openapi: 3.2.0
info:
  title: S1 Dev Account API
  version: 1.0.0
  x-guidance: Search1API provides web search, news aggregation, URL crawling, webpage screenshots, sitemap extraction, trending topics, content extraction, and deep crawling. All paid endpoints accept POST with a JSON body. Use POST /search with a "query" field for web search. Use POST /news with a "query" field for news. Use POST /ask with a natural-language "query" to have Search1API choose the engines and time window and return only relevant results (API key only). Use POST /crawl with a "url" field to crawl a page. Use POST /screenshot with a "url" field to render a PNG, JPEG, or WebP image. Use POST /sitemap with a "url" field to extract sitemap URLs. Use POST /trending with a "search_service" field for trends. Use POST /extract with a "url" field for structured content extraction. Use POST /deepcrawl with a "url" field for deep multi-page crawling.
  description: 'Operations tagged Account across 2 of this provider''s published API definitions: search1api-openapi.json, s1-dev-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.search1api.com
tags:
- name: Account
paths:
  /usage:
    get:
      operationId: usage
      summary: Get API key usage statistics
      description: Return the remaining credit balance for the authenticated account. Use it to check headroom before starting an expensive job such as a deepcrawl, or to confirm an API key works. Free to call.
      tags:
      - Account
      x-codeSamples:
      - id: js
        lang: ts
        label: TypeScript SDK
        source: 'import { Search1API } from ''@search1api/client'';


          const client = new Search1API();

          const usage = await client.usage(''month'');


          console.log(usage);'
      - id: python
        lang: python
        label: Python SDK
        source: 'from search1api import Search1API


          client = Search1API()

          usage = client.usage("month")


          print(usage)'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      security:
      - bearerAuth: []
      parameters:
      - in: query
        name: period
        required: false
        schema:
          type: string
          enum:
          - day
          - week
          - month
          - year
    servers:
    - url: https://api.search1api.com
components:
  schemas:
    ApiError:
      type: object
      description: 'Search1API error. Every JSON error carries `ok: false`, `error` (a short status-derived label) and `message` (human-readable detail); validation failures add `errors`. Payment challenges may use RFC 9457 problem detail fields.'
      properties:
        ok:
          type: boolean
          enum:
          - false
        error:
          type: string
        message:
          type: string
        errors:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
              message:
                type: string
              code:
                type: string
        type:
          type: string
          format: uri
        title:
          type: string
        status:
          type: integer
        detail:
          type: string
      additionalProperties: true
    UsageResponse:
      type: object
      required:
      - usage
      - credential_type
      properties:
        usage:
          type: integer
          minimum: 0
        user_id:
          type:
          - string
          - 'null'
        credential_type:
          type: string
          enum:
          - api_key
          - oauth
        client_id:
          type:
          - string
          - 'null'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
x-refined-from:
- search1api-openapi.json
- s1-dev-openapi.yml
x-discovery:
  ownershipProofs: []