Arkova Search API

openapi: 3.2.0
info:
  title: Arkova Verification Search API
  version: 1.0.1
  description: Programmatic credential verification API. Verify credentials anchored on the Bitcoin network. Worker-generated v1 JSON errors expose common top-level code and message fields. The legacy error field is retained unchanged (string or object), along with details and quota context, for existing integrations. Parse code and message for new integrations. Upstream gateway errors may not be JSON. Revision 1.0.1 restores legacy label and DIPLOMA inputs and clarifies receipts and webhook payloads; the endpoint version remains v1.
  contact:
    name: Arkova Support
    url: https://arkova.ai
servers:
- url: /api/v1
  description: Verification API v1
security:
- ApiKeyBearer: []
- ApiKeyHeader: []
tags:
- name: Search
  description: Anonymous public search across organizations, members, records and imported public records
paths:
  /public/search:
    get:
      summary: Public search (organizations, members, records, imported public records)
      description: 'Anonymous search across everything Arkova publishes: public organizations, opted-in public member profiles, public records (by text, or exactly by an `ARK-...` record ID), and imported public records from the public-record pipeline. Works with no API key at the anonymous tier (100 req/min/IP); an API key only moves the caller to the 1,000 req/min keyed tier and needs no scope. Returns public projections only: `public_id` plus derived fields and public page URLs, never an internal UUID or email. Groups run independently; a group whose backend failed is listed in `unavailable` and returned empty, and the call is a 503 only when every requested group failed. Imported-record search is plain text and does not depend on ENABLE_SEMANTIC_SEARCH.'
      operationId: publicSearch
      tags:
      - Search
      security:
      - ApiKeyBearer: []
      - ApiKeyHeader: []
      - {}
      parameters:
      - name: q
        in: query
        required: true
        description: Search text (2-200 characters after trimming). An `ARK-...` value is resolved exactly for the anchors group.
        schema:
          type: string
          minLength: 2
          maxLength: 200
      - name: type
        in: query
        required: false
        description: Which group to search; `all` searches every group.
        schema:
          type: string
          enum:
          - all
          - orgs
          - members
          - anchors
          - imports
          default: all
      - name: limit
        in: query
        required: false
        description: Maximum results per group.
        schema:
          type: integer
          minimum: 1
          maximum: 50
          default: 10
      responses:
        '200':
          description: Grouped public search results. All four `results` keys are always present; groups not requested are empty.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicSearchResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          description: Every requested group failed, or ENABLE_VERIFICATION_API is off (worker-wide gate for /api/v1/*).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
components:
  responses:
    RateLimited:
      description: Rate limit exceeded
      headers:
        Retry-After:
          schema:
            type: integer
          description: Seconds until retry is allowed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    BadRequest:
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
  schemas:
    ApiError:
      type: object
      required:
      - error
      properties:
        error:
          oneOf:
          - type: string
          - type: object
            additionalProperties: true
            properties:
              code:
                type: string
              message:
                type: string
        code:
          type: string
          description: Common machine-readable error code; legacy error remains unchanged.
        message:
          type: string
    PublicSearchResponse:
      type: object
      additionalProperties: false
      required:
      - query
      - type
      - results
      - total
      - unavailable
      properties:
        query:
          type: string
        type:
          type: string
          enum:
          - all
          - orgs
          - members
          - anchors
          - imports
        results:
          type: object
          additionalProperties: false
          required:
          - orgs
          - members
          - anchors
          - imports
          properties:
            orgs:
              type: array
              items:
                type: object
                additionalProperties: false
                required:
                - public_id
                - display_name
                - verified
                - credential_count
                - profile_url
                properties:
                  public_id:
                    type:
                    - string
                    - 'null'
                  display_name:
                    type: string
                  verified:
                    type: boolean
                  credential_count:
                    type: integer
                    minimum: 0
                  profile_url:
                    type: string
                    format: uri
                    description: Public issuer page.
            members:
              type: array
              items:
                type: object
                additionalProperties: false
                required:
                - public_id
                - display_name
                - headline
                - avatar_url
                - organization_name
                - organization_public_id
                - profile_url
                properties:
                  public_id:
                    type: string
                  display_name:
                    type: string
                  headline:
                    type:
                    - string
                    - 'null'
                  avatar_url:
                    type:
                    - string
                    - 'null'
                  organization_name:
                    type:
                    - string
                    - 'null'
                  organization_public_id:
                    type:
                    - string
                    - 'null'
                  profile_url:
                    type: string
                    format: uri
                    description: Public member profile page.
            anchors:
              type: array
              items:
                type: object
                additionalProperties: false
                required:
                - public_id
                - title
                - credential_type
                - status
                - created_at
                - verify_url
                properties:
                  public_id:
                    type: string
                  title:
                    type: string
                  credential_type:
                    type:
                    - string
                    - 'null'
                  status:
                    type: string
                  created_at:
                    type:
                    - string
                    - 'null'
                    format: date-time
                  verify_url:
                    type: string
                    format: uri
                    description: Public record verification page.
            imports:
              type: array
              items:
                type: object
                additionalProperties: false
                required:
                - public_id
                - title
                - source
                - record_type
                - source_url
                - secured_at
                - verify_url
                properties:
                  public_id:
                    type: string
                  title:
                    type: string
                  source:
                    type:
                    - string
                    - 'null'
                    description: Public-record pipeline source key, e.g. edgar, uspto.
                  record_type:
                    type:
                    - string
                    - 'null'
                  source_url:
                    type:
                    - string
                    - 'null'
                    description: Original public source page.
                  secured_at:
                    type:
                    - string
                    - 'null'
                    format: date-time
                    description: Network Observed Time.
                  verify_url:
                    type: string
                    format: uri
                    description: Public record verification page.
        total:
          type: integer
          minimum: 0
          description: Sum of all group lengths.
        unavailable:
          type: array
          items:
            type: string
            enum:
            - orgs
            - members
            - anchors
            - imports
          description: Groups whose backend failed for this request (returned empty).
  securitySchemes:
    ApiKeyBearer:
      type: http
      scheme: bearer
      description: 'API key as Bearer token: `Authorization: Bearer ak_live_...`'
    ApiKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
      description: 'API key via header: `X-API-Key: ak_live_...`'
    SupabaseJWT:
      type: http
      scheme: bearer
      description: Supabase JWT for key management endpoints