Homespun API

openapi: 3.1.0
info:
  title: Homespun API
  version: '2026-11-11'
  description: 'GENERATED FROM DOCUMENTATION by API Evangelist on 2026-11-11: 18 operation(s) read from 14 public documentation page(s) (each
    operation names its page in x-source). This is not the provider''s published contract; Homespun has published no machine-readable contract
    that the pipeline could find. Engine: local.'
  x-evidence-tiers:
    code-example: 0
    documentation: 18
    pages-with-code: 0
    pages-read: 14
  x-generated-from: documentation
  x-provenance: generated
  x-authored-by: API Evangelist
  x-generated: '2026-11-11'
  x-generator: generate-contract-from-docs.py
  x-engine: local
  x-sources:
  - https://docs.homespun.dev/reference/api.md
  - https://docs.homespun.dev/reference/errors.md
  - https://docs.homespun.dev/agents/cli-reference
  - https://docs.homespun.dev/agents/cli-reference.md
  - https://docs.homespun.dev/agents/manifest-reference
  - https://docs.homespun.dev/agents/manifest-reference.md
  - https://docs.homespun.dev/agents/receive-data
  - https://docs.homespun.dev/agents/agent-tasks
  - https://docs.homespun.dev/agents/collection-retention
  - https://docs.homespun.dev/agents/collection-read
  - https://docs.homespun.dev/agents/receive-data.md
  - https://docs.homespun.dev/agents/agent-tasks.md
  - https://docs.homespun.dev/agents/collection-retention.md
  - https://docs.homespun.dev/agents/collection-read.md
paths:
  /_hs/tasks:
    get:
      operationId: get_hs_tasks
      tags:
      - Hs
      summary: 'A page can ask about its own row:'
      x-source: https://docs.homespun.dev/agents/agent-tasks
      parameters:
      - name: collection
        in: query
        required: false
        schema:
          type: string
        description: The collection name to query.
      - name: row
        in: query
        required: false
        schema:
          type: string
        description: The row identifier to query.
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetHsTasksResponse'
      x-evidence:
        kind: documentation
  /authorize:
    get:
      operationId: get_authorize
      tags:
      - Authorize
      summary: Restart sign‑in to obtain a fresh session grant.
      x-source: https://docs.homespun.dev/reference/errors.md
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /v1/apps:
    get:
      operationId: get_v1_apps
      tags:
      - Apps
      summary: List your apps (GET /v1/apps).
      x-source: https://docs.homespun.dev/agents/cli-reference
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
    post:
      operationId: post_v1_apps
      tags:
      - Apps
      summary: Create a new app (POST /v1/apps).
      x-source: https://docs.homespun.dev/agents/cli-reference
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /v1/apps/{id}/collections/{name}:
    get:
      operationId: get_v1_apps_id_collections_name
      tags:
      - Apps
      summary: Reading a collection
      x-source: https://docs.homespun.dev/agents/collection-read
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: name
        in: path
        required: true
        schema:
          type: string
      - name: since
        in: query
        required: false
        schema:
          type: string
        description: Opaque continuation token returned from a previous page to fetch the next page
      - name: limit
        in: query
        required: false
        schema:
          type: string
        description: Maximum number of rows to return in the page (default up to 100, max 1000)
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetV1AppsIdCollectionsNameResponse'
      x-evidence:
        kind: documentation
  /v1/apps/{id}/collections/{name}/{key}:
    patch:
      operationId: patch_v1_apps_id_collections_name_key
      tags:
      - Apps
      summary: Avoid lost updates with if_match
      x-source: https://docs.homespun.dev/agents/receive-data
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: name
        in: path
        required: true
        schema:
          type: string
      - name: key
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchV1AppsIdCollectionsNameKeyRequest'
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PatchV1AppsIdCollectionsNameKeyResponse'
      x-evidence:
        kind: documentation
  /v1/apps/{id}/collections/{name}/{key}/restore:
    post:
      operationId: post_v1_apps_id_collections_name_key_restore
      tags:
      - Apps
      summary: Restore a soft‑deleted row before updating or deleting it.
      x-source: https://docs.homespun.dev/reference/errors.md
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: name
        in: path
        required: true
        schema:
          type: string
      - name: key
        in: path
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /v1/apps/{id}/connections:
    get:
      operationId: get_v1_apps_id_connections
      tags:
      - Apps
      summary: List connections on the app.
      x-source: https://docs.homespun.dev/reference/errors.md
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /v1/apps/{id}/connections/{name}:
    delete:
      operationId: delete_v1_apps_id_connections_name
      tags:
      - Apps
      summary: Delete an unused connection before creating another.
      x-source: https://docs.homespun.dev/reference/errors.md
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: name
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /v1/apps/{id}/domain:
    delete:
      operationId: delete_v1_apps_id_domain
      tags:
      - Apps
      summary: Remove the current custom domain before adding another.
      x-source: https://docs.homespun.dev/reference/errors.md
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
    post:
      operationId: post_v1_apps_id_domain
      tags:
      - Apps
      summary: Add a custom domain to the app.
      x-source: https://docs.homespun.dev/reference/errors.md
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /v1/apps/{id}/ingest-hooks/{name}/backfill:
    post:
      operationId: post_v1_apps_id_ingest_hooks_name_backfill
      tags:
      - Apps
      summary: Backfill a hook’s collection with historical data (POST /v1/apps/:id/ingest-hooks/:name/backfill).
      x-source: https://docs.homespun.dev/agents/cli-reference
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: name
        in: path
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /v1/apps/{id}/restore:
    post:
      operationId: post_v1_apps_id_restore
      tags:
      - Apps
      summary: Restores a soft-deleted app with all its data, returning the app detail record. Idempotent on a live app.
      x-source: https://docs.homespun.dev/reference/api.md
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /v1/apps/{id}/versions:
    post:
      operationId: post_v1_apps_id_versions
      tags:
      - Apps
      summary: Redeploy an existing app (POST /v1/apps/:id/versions).
      x-source: https://docs.homespun.dev/agents/cli-reference
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /v1/apps/{id}/webhooks/deliveries:
    get:
      operationId: get_v1_apps_id_webhooks_deliveries
      tags:
      - Apps
      summary: The delivery log is readable through GET /v1/apps/:id/webhooks/deliveries
      x-source: https://docs.homespun.dev/agents/manifest-reference
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /v1/attachments:
    post:
      operationId: post_v1_attachments
      tags:
      - Attachments
      summary: Upload the attachment and use the returned attachment_id.
      x-source: https://docs.homespun.dev/reference/errors.md
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /v1/ingest:
    post:
      operationId: post_v1_ingest
      tags:
      - Ingest
      summary: Send an inbound hook payload; the request must match the ingest rule.
      x-source: https://docs.homespun.dev/reference/errors.md
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /v1/register:
    post:
      operationId: post_v1_register
      tags:
      - Register
      summary: Register an agent directly via POST /v1/register.
      x-source: https://docs.homespun.dev/agents/cli-reference
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
components:
  schemas:
    GetHsTasksResponse:
      type: object
      properties:
        status:
          type: string
          description: One of queued, working, done, failed, or expired.
    GetV1AppsIdCollectionsNameResponse:
      type: object
      properties:
        rows:
          type: array
          description: Array of collection rows for this page
        next_cursor:
          type: string
          description: Opaque token for the next page; null on the last page
        has_more:
          type: boolean
          description: True when more rows remain after this page
    PatchV1AppsIdCollectionsNameKeyRequest:
      type: object
      properties:
        id:
          type: string
          description: The row identifier.
        status:
          type: string
          description: Arbitrary payload field.
        if_match:
          type: integer
          description: Version to match for optimistic concurrency.
      required:
      - id
    PatchV1AppsIdCollectionsNameKeyResponse:
      type: object
      properties:
        ok:
          type: boolean
          description: Acknowledgement of successful write.
tags:
- name: Apps
- name: Attachments
- name: Authorize
- name: Hs
- name: Ingest
- name: Register