openapi: 3.0.3
info:
  title: Signer Metrics Accounts Atlas API
  description: Welcome to the API reference overview for the Signer Metrics API.
  version: 1.0.3
servers:
- url: https://api.hiro.so/
  description: mainnet
- url: https://api.testnet.hiro.so/
  description: testnet
tags:
- name: Atlas
  description: Operations related to the Atlas global namespace.
paths:
  /v2/attachments/{hash}:
    get:
      summary: Get attachment by hash
      tags:
      - Atlas
      security: []
      operationId: getAttachment
      description: 'Get an attachment by its hash. Attachments are content stored in the Atlas network.


        The attachment hash is a 40-character hex string (SHA-1 hash).

        '
      parameters:
      - name: hash
        in: path
        required: true
        description: Hex-encoded SHA-1 hash of the attachment (40 characters)
        schema:
          type: string
          pattern: ^[0-9a-f]{40}$
      responses:
        '200':
          description: The attachment content
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttachmentData'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
  /v2/attachments/inv:
    get:
      summary: Get attachment inventory
      tags:
      - Atlas
      security: []
      operationId: getAttachmentsInventory
      description: 'Get inventory of attachments for a given index block hash and page range.

        This returns a bitfield indicating which attachments are available.

        '
      parameters:
      - name: index_block_hash
        in: query
        required: true
        description: Hex-encoded index block hash (64 characters)
        schema:
          type: string
          pattern: ^[0-9a-f]{64}$
      - name: pages_indexes
        in: query
        required: true
        description: 'Comma-separated list of page indexes to query.

          - Maximum 8 pages per request

          - Each index must be 0-4294967295 (u32 range)

          - Values outside u32 range return 400 Bad Request

          '
        schema:
          type: string
          example: 1,2,3
          pattern: ^[0-9]{1,10}(,[0-9]{1,10}){0,7}$
      responses:
        '200':
          description: Attachment inventory bitfield
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttachmentInventory'
              examples:
                attachment-inventory:
                  summary: Attachment inventory response
                  value:
                    block_id: 0123456789abcdef0123456789abcdef0123456789abcdef
                    pages:
                    - index: 1
                      inventory:
                      - 255
                      - 0
                      - 255
                      - 0
                    - index: 2
                      inventory:
                      - 0
                      - 255
                      - 0
                      - 255
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    AttachmentData:
      $ref: ./components/schemas/attachment-data.schema.yaml
    AttachmentInventory:
      $ref: ./components/schemas/attachment-inventory.schema.yaml
  responses:
    NotFound:
      description: Not found
      content:
        text/plain:
          schema:
            type: string
          example: Not found
    BadRequest:
      description: Bad request
      content:
        text/plain:
          schema:
            type: string
          example: Bad request
externalDocs:
  url: https://github.com/hirosystems/signer-metrics-api
  description: Source Repository