app.yml

openapi: "3.0.0"
info:
  title: Indexd Application API
  description: >
    The Application API allows developers to pin and unpin slabs—collections of erasure-coded data shards—on the Sia network using Indexd.
    Once pinned, Indexd ensures the data remains healthy and available by monitoring and maintaining the underlying storage.
  version: 1.0.0

servers:
  - url: http://localhost:9982/api

tags:
  - name: hosts
    description: Fetch usable hosts
  - name: objects
    description: List, save, retrieve and delete objects
  - name: slabs
    description: List, pin, unpin and retrieve pinned slab details
  - name: accounts
    description: Retrieve current account

paths:
  /account:
    get:
      tags:
        - accounts
      summary: Retrieve details of current authenticated account including used storage and remaining storage
      responses:
        "200":
          description: Details of the account
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AppAccountResponse"
        "404":
          description: Account not found

  /hosts:
    get:
      tags:
        - hosts
      summary: List usable hosts
      parameters:
        - name: limit
          in: query
          description: The maximum number of hosts to return
          schema:
            type: integer
            minimum: 1
            maximum: 500
            default: 100
        - name: offset
          in: query
          description: The number of hosts to skip
          schema:
            type: integer
            minimum: 0
            default: 0
        - name: protocol
          in: query
          description: Filter hosts by protocol
          schema:
            type: string
            enum: [siamux, quic]
      operationId: listHosts
      responses:
        "200":
          description: A list of usable hosts
          content:
            application/json:
              schema:
                type: object
                properties:
                  hosts:
                    type: array
                    items:
                      $ref: "#/components/schemas/HostInfo"

      x-codeSamples:
        - lang: Go
          label: Go
          source: |
            package main

            import (
              "context"
              "go.sia.tech/indexd/app"
              "go.sia.tech/core/types"
            )

            func main() {
              var appKey types.PrivateKey
              client, err := app.NewClient("http://localhost:9982", appKey)
              hosts, err := client.Hosts(context.Background())
              // ...
            }

  /objects:
    get:
      tags:
        - objects
      summary: List all objects
      parameters:
        - name: limit
          in: query
          description: The maximum number of objects to return
          schema:
            type: integer
            minimum: 1
            maximum: 500
            default: 100
        - name: key
          in: query
          description: The object key that is used as an offset when paginating
          schema:
            $ref: "#/components/schemas/Hash256"
        - name: after
          in: query
          description: The updated at timestamp that is used as an offset when paginating
          schema:
            type: string
            format: date-time
      responses:
        "200":
          description: A list of object events
          content:
            application/json:
              schema:
                type: object
                properties:
                  slabs:
                    type: array
                    items:
                      $ref: "#/components/schemas/ObjectEvent"
    post:
      tags:
        - objects
      summary: Create or update an object
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PinObjectRequest"
      responses:
        "200":
          description: Object created or updated successfully
        "400":
          description: Object has no slabs, metadata exceeds size limit, or object contains unpinned slab
  /objects/{key}:
    get:
      tags:
        - objects
      summary: Get details of an object
      parameters:
        - name: key
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/Hash256"
      responses:
        "200":
          description: Details of the object
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SealedObject"
        "404":
          description: Object not found
    delete:
      tags:
        - objects
      summary: Delete an object
      parameters:
        - name: key
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/Hash256"
      responses:
        "200":
          description: Object deleted successfully
        "404":
          description: Object not found
  /objects/{key}/shared:
    get:
      tags:
        - objects
      summary: Get a shared object
      parameters:
        - name: key
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/Hash256"
      responses:
        "200":
          description: The shared object
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SharedObject"
        "404":
          description: Object not found

  /slabs:
    get:
      tags:
        - slabs
      summary: List all pinned slabs
      parameters:
        - name: limit
          in: query
          description: The maximum number of slab IDs to return
          schema:
            type: integer
            minimum: 1
            maximum: 500
            default: 100
        - name: offset
          in: query
          description: The number of slab IDs to skip
          schema:
            type: integer
            minimum: 0
            default: 0
      operationId: listSlabs
      responses:
        "200":
          description: A list of pinned slabs
          content:
            application/json:
              schema:
                type: object
                properties:
                  slabs:
                    type: array
                    items:
                      $ref: "#/components/schemas/SlabID"

      x-codeSamples:
        - lang: Go
          label: Go
          source: |
            package main

            import (
              "context"
              "go.sia.tech/indexd/app"
              "go.sia.tech/core/types"
            )

            func main() {
              var appKey types.PrivateKey
              client, err := app.NewClient("http://localhost:9982", appKey)
              ids, err := client.SlabIDs(context.Background())
              // ...
            }
    post:
      tags:
        - slabs
      summary: Pin a slab to the indexer
      operationId: pinSlab
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                encryptionKey:
                  allOf:
                    - $ref: "#/components/schemas/EncryptionKey"
                    - description: The encryption key used to encrypt the shards
                minShards:
                  type: integer
                  minimum: 1
                  format: uint
                  description: The number of data shards a piece gets erasure-coded into
                sectors:
                  type: array
                  items:
                    type: object
                    properties:
                      root:
                        allOf:
                          - $ref: "#/components/schemas/Hash256"
                          - description: The root of the sector
                      hostKey:
                        allOf:
                          - $ref: "#/components/schemas/PublicKey"
                          - description: The public key of the host that stores the sector
      responses:
        "201":
          description: Slab pinned successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  slabID:
                    allOf:
                      - $ref: "#/components/schemas/SlabID"
                      - description: The ID of the pinned slab

      x-codeSamples:
        - lang: Go
          label: Go
          source: |
            package main

            import (
              "context"
              "go.sia.tech/indexd/app"
              "go.sia.tech/indexd/slabs"
              "go.sia.tech/core/types"
            )

            func main() {
              var appKey types.PrivateKey
              client, err := app.NewClient("http://localhost:9982", appKey)
              var params slabs.SlabPinParams
              id, err := client.PinSlab(context.Background(), params)
              // ...
            }

  /slabs/{slabid}:
    get:
      tags:
        - slabs
      summary: Get details of a pinned slab
      operationId: getSlab
      parameters:
        - name: slabid
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Details of the pinned slab
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    allOf:
                      - $ref: "#/components/schemas/SlabID"
                      - description: The ID of the slab
                  encryptionKey:
                    allOf:
                      - $ref: "#/components/schemas/EncryptionKey"
                      - description: The encryption key used for the slab
                  minShards:
                    type: integer
                    description: The minimum number of shards required for the slab
                  sectors:
                    type: array
                    items:
                      type: object
                      properties:
                        root:
                          allOf:
                            - $ref: "#/components/schemas/Hash256"
                            - description: The root hash of the sector
                        hostKey:
                          allOf:
                            - $ref: "#/components/schemas/PublicKey"
                            - description: The public key of the host storing the sector
        "404":
          description: Slab not found

      x-codeSamples:
        - lang: Go
          label: Go
          source: |
            package main

            import (
              "context"
              "go.sia.tech/indexd/app"
              "go.sia.tech/indexd/slabs"
              "go.sia.tech/core/types"
            )

            func main() {
              var appKey types.PrivateKey
              client, err := app.NewClient("http://localhost:9982", appKey)
              var id slabs.SlabID
              s, err := client.Slab(context.Background(), id)
              // ...
            }
    delete:
      tags:
        - slabs
      summary: Unpin a slab from the indexer
      operationId: unpinSlab
      parameters:
        - name: slabid
          in: path
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Slab unpinned successfully

      x-codeSamples:
        - lang: Go
          label: Go
          source: |
            package main

            import (
              "context"
              "go.sia.tech/indexd/app"
              "go.sia.tech/indexd/slabs"
              "go.sia.tech/core/types"
            )

            func main() {
              var appKey types.PrivateKey
              client, err := app.NewClient("http://localhost:9982", appKey)
              var id slabs.SlabID
              err = client.UnpinSlab(context.Background(), id)
              // ...
            }

  /slabs/prune:
    post:
      tags:
        - slabs
      summary: Unpin all slabs not used by an object currently pinned by the user
      operationId: pruneSlabs
      parameters:
        - name: before
          in: query
          description: Only slabs pinned before this timestamp are eligible for pruning. Defaults to one hour ago.
          schema:
            type: string
            format: date-time
      responses:
        "200":
          description: Slabs pruned successfully

  /auth/connect:
    post:
      tags:
        - auth
      summary: Request application connection to the indexer
      description: >
        Initiates a connection request. The request must be signed with an ephemeral ed25519 key
        using the signed URL scheme. The server binds the connection flow to that ephemeral key —
        subsequent calls to the status and register endpoints must be signed with the same key.
      operationId: requestAppConnection
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - appID
                - name
                - description
                - serviceURL
              properties:
                appID:
                  $ref: "#/components/schemas/Hash256"
                  description: Unique, stable identifier for the application.
                name:
                  type: string
                  maxLength: 128
                  description: Application name
                description:
                  type: string
                  maxLength: 1024
                  description: Application description
                logoURL:
                  type: string
                  format: uri
                  maxLength: 2048
                  description: URL of the application logo
                serviceURL:
                  type: string
                  format: uri
                  maxLength: 2048
                  description: URL of the application service
                callbackURL:
                  type: string
                  format: uri
                  maxLength: 2048
                  description: Optional URL the indexer can redirect to after approval
      responses:
        "200":
          description: Application connection request accepted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RegisterAppResponse"
        "400":
          description: Invalid request (missing required fields or field exceeds maximum length)
        "409":
          description: Application already connected
        "429":
          description: Too many requests — per-IP rate limit exceeded

      x-codeSamples:
        - lang: Go
          label: Go
          source: |
            package main

            import (
              "context"
              "go.sia.tech/indexd/app"
              "go.sia.tech/core/types"
              "lukechampine.com/frand"
            )

            var appID = frand.Entropy256() // app ID should be constant for your application, not random

            func main() {
              client := app.NewClient("http://localhost:9982")
              ephemeralKey := types.GeneratePrivateKey()
              connectResp, err := client.RequestAppConnection(context.Background(), ephemeralKey, app.RegisterAppRequest{
                AppID:       appID,
                Name:        "Test App",
                Description: "A test application",
                LogoURL:     "https://example.com/logo.png",
                ServiceURL:  "https://example.com",
                CallbackURL: "https://example.com/connected",
              })
              ...
            }

  /auth/check:
    get:
      tags:
        - auth
      summary: Check if application is authenticated
      operationId: checkAppAuth
      responses:
        "204":
          description: Application is authenticated
        "401":
          description: Application is not authenticated
        "400":
          description: Invalid signature

      x-codeSamples:
        - lang: Go
          label: Go
          source: |
            package main

            import (
              "context"
              "go.sia.tech/indexd/app"
              "go.sia.tech/core/types"
            )

            func main() {
              var appKey types.PrivateKey
              client := app.NewClient("http://localhost:9982")
              ok, err := client.CheckAppAuth(context.Background(), appKey)
              ...
            }

  /auth/connect/{requestID}:
    get:
      tags:
        - auth
      summary: Returns connection request UI HTML page.
      operationId: connectAuthUI
      parameters:
        - name: requestID
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: HTML authorization page
          content:
            text/html: {}
        "404":
          description: Unknown request ID

    post:
      tags:
        - auth
      summary: Approve or reject an application connection request.  Requires HTTP Basic authentication.
      operationId: approveAppRequest
      parameters:
        - name: requestID
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                approve:
                  type: boolean
                  description: Whether to approve the application connection request or not.
      responses:
        "204":
          description: Request processed successfully
        "401":
          description: Invalid connect key
        "403":
          description: Connect key exhausted
        "404":
          description: Request invalid or expired

  /auth/connect/{requestID}/status:
    get:
      tags:
        - auth
      summary: Check the status of a connection request
      description: >
        Returns whether the user has approved or rejected the connection request. Must be signed
        with the same ephemeral key used in the initial `POST /auth/connect` request. If approved,
        the response includes the `userSecret` used to derive the application key.
      operationId: authConnectStatus
      parameters:
        - name: requestID
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Connection request status
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AuthConnectStatusResponse"
        "401":
          description: Signed with a different ephemeral key than the one used to initiate the request
        "404":
          description: Request invalid or expired

  /auth/connect/{requestID}/register:
    post:
      tags:
        - auth
      summary: Finalize application registration after approval
      description: >
        Registers the application key. The request URL must be signed with the ephemeral key from
        the initial connect request. The body contains the application public key and a
        proof-of-possession signature: `appKey.Sign(hash("registerAppKey" + ephemeralPubKey + requestID))`.
        This proves the caller both controls the ephemeral key and knows the private key of the app
        key being registered.
      operationId: authRegister
      parameters:
        - name: requestID
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - appKey
                - signature
              properties:
                appKey:
                  allOf:
                    - $ref: "#/components/schemas/PublicKey"
                    - description: The application public key to register
                signature:
                  type: string
                  format: byte
                  description: >
                    ed25519 signature by `appKey` over `hash("registerAppKey" + ephemeralPubKey + requestID)`,
                    proving ownership of the application key
      responses:
        "204":
          description: Application registered successfully
        "401":
          description: Signed with a different ephemeral key than the one used to initiate the request, or invalid proof-of-possession signature
        "403":
          description: Connect key exhausted or request not approved
        "404":
          description: Unknown request ID
        "410":
          description: Request expired

components:
  schemas:
    AuthConnectStatusResponse:
      $ref: "./components.yml#/components/schemas/AuthConnectStatusResponse"
    EncryptionKey:
      $ref: "./components.yml#/components/schemas/EncryptionKey"
    Hash256:
      $ref: "./components.yml#/components/schemas/Hash256"
    HostInfo:
      $ref: "./components.yml#/components/schemas/HostInfo"
    Account:
      $ref: "./components.yml#/components/schemas/Account"
    AppAccountResponse:
      $ref: "./components.yml#/components/schemas/AppAccountResponse"
    SealedObject:
      $ref: "./components.yml#/components/schemas/SealedObject"
    ObjectEvent:
      $ref: "./components.yml#/components/schemas/ObjectEvent"
    PublicKey:
      $ref: "./components.yml#/components/schemas/PublicKey"
    RegisterAppResponse:
      $ref: "./components.yml#/components/schemas/RegisterAppResponse"
    SlabID:
      $ref: "./components.yml#/components/schemas/SlabID"
    SlabSlice:
      $ref: "./components.yml#/components/schemas/SlabSlice"
    PinObjectRequest:
      $ref: "./components.yml#/components/schemas/PinObjectRequest"
    ObjectSlab:
      $ref: "./components.yml#/components/schemas/ObjectSlab"
    SharedObject:
      $ref: "./components.yml#/components/schemas/SharedObject"