Hookdeck Topics API

openapi: 3.2.0
info:
  title: Outpost Topics API
  version: 0.0.1
  description: 'The Outpost API is a REST-based JSON API for managing tenants, destinations, and publishing events.


    Outpost runs in two deployment models: **managed** (hosted by Hookdeck) and **self-hosted**. They differ in where the API is served and in which API key authenticates server-side calls. On managed Outpost, use a Hookdeck project API key from your Outpost project. On self-hosted Outpost, use the key set in the `API_KEY` environment variable. A few endpoints exist in one model only and say so in their description.'
  contact:
    name: Outpost Support
    email: support@hookdeck.com
    url: https://hookdeck.com/docs/outpost
servers:
- url: https://api.outpost.hookdeck.com/2025-07-01
  description: Managed Outpost, hosted by Hookdeck at `api.outpost.hookdeck.com`. The Hookdeck Event Gateway API at `api.hookdeck.com` is a separate API.
- url: http://localhost:3333/api/v1
  description: Self-hosted Outpost, at its default local address. A deployed instance serves the same paths under its own host.
security:
- AdminApiKey: []
- TenantJwt: []
tags:
- name: Topics
  description: Returns the list of topics configured for this Outpost deployment. Tenants subscribe their destinations to topics from this list. Topics are defined via your configuration file and not a specific Create Topic API.
paths:
  /topics:
    get:
      tags:
      - Topics
      summary: List Available Topics
      description: Returns a list of available event topics configured in the Outpost instance.
      operationId: listTopics
      responses:
        '200':
          description: A list of topic names.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
              examples:
                TopicsListExample:
                  value:
                  - user.created
                  - user.updated
                  - order.shipped
                  - inventory.updated
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    APIErrorResponse:
      type: object
      description: Standard error response format.
      properties:
        status:
          type: integer
          description: HTTP status code.
          example: 422
        message:
          type: string
          description: Human-readable error message.
          example: validation error
        data:
          description: Additional error details. For validation errors, this is an array of human-readable messages.
          oneOf:
          - type: array
            items:
              type: string
            description: Array of validation error messages.
            example:
            - email is required
            - password must be at least 6 characters
          - type: object
            additionalProperties: true
            description: Additional contextual data about the error.
  responses:
    Unauthorized:
      description: Missing or invalid authentication credentials.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/APIErrorResponse'
    InternalServerError:
      description: Unexpected server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/APIErrorResponse'
  securitySchemes:
    AdminApiKey:
      type: http
      scheme: bearer
      description: "Bearer token for server-side calls. Where it comes from depends on the\ndeployment:\n\n- **Managed:** a Hookdeck **project API key belonging to your\n  Outpost project** (Hookdeck Dashboard → your Outpost project →\n  Settings → Secrets). A key from a different Hookdeck project\n  authenticates but returns `404` on most Outpost routes.\n- **Self-hosted:** the admin API key set in the `API_KEY` environment\n  variable.\n\nThe scheme is named for the self-hosted credential. Managed Outpost has\nno separate admin key to create. The project API key takes its place.\n"
    TenantJwt:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: "Per-tenant JWT token valid for 24 hours.\n\n**JWT Structure:**\nThe token is a standard JWT signed with HS256 algorithm containing the following claims:\n- `iss` (issuer): Always \"outpost\"\n- `sub` (subject): The tenant_id this token is scoped to\n- `iat` (issued at): Unix timestamp when the token was created\n- `exp` (expiration): Unix timestamp when the token expires (24 hours after issuance)\n\n**Example decoded payload:**\n```json\n{\n  \"iss\": \"outpost\",\n  \"sub\": \"tenant_123\",\n  \"iat\": 1704067200,\n  \"exp\": 1704153600\n}\n```\n"
x-provenance:
  method: harvested
  publisher: Hookdeck
  source: https://raw.githubusercontent.com/hookdeck/outpost/main/docs/apis/openapi.yaml
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)