AutoShort Webhooks API

openapi: 3.2.0
info:
  title: AutoShort Webhooks API
  version: 1.0.0
  summary: Create AI short videos from a topic or a reviewed script, poll them to completion, and read credits.
  description: 'Authenticate every request with an API key: `Authorization: Bearer sk_live_...` (create one in the dashboard). Rendering is asynchronous: POST /api/v1/videos/generate (or render a draft) returns a video id; poll GET /api/v1/videos/{id} every 20-30 seconds until status is COMPLETED or FAILED, or register a webhook for video.completed / video.failed. Every render costs credits; a short balance is refused up front (402 INSUFFICIENT_CREDITS). Nothing in this API buys credits. Exception, no key needed: POST /api/x402/videos buys one video per call with an x402 USDC payment (tag "Pay per call (x402)", only when enabled on the server). Director mode (drafts) lets you agree a script first: creating and editing a draft is free, only POST /api/v1/drafts/{id}/render charges. The same capabilities (plus product ads, image-to-video, series and publishing) are available over MCP at https://autoshort.org/api/mcp (OAuth 2.1 or API key). Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. Error bodies look like {"error": "...", "code": "..."}; some add top-level fields (see each endpoint). Not covered here: API key management (needs a signed-in dashboard session) and the web-app routes behind the MCP product-ad / image-to-video / chat tools.'
  termsOfService: https://autoshort.org/en/terms
  contact:
    name: AutoShort
    url: https://autoshort.org
servers:
- url: https://autoshort.org
security:
- bearerAuth: []
tags:
- name: Webhooks
  description: Signed callbacks for video.completed / video.failed.
paths:
  /api/v1/webhooks:
    get:
      operationId: listWebhooks
      tags:
      - Webhooks
      summary: List registered webhooks
      description: Secrets are not shown. Any valid API key works (no specific scope is checked).
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Webhooks.
          content:
            application/json:
              schema:
                type: object
                properties:
                  webhooks:
                    type: array
                    items:
                      $ref: '#/components/schemas/Webhook'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      operationId: createWebhook
      tags:
      - Webhooks
      summary: Register an https URL for video.completed / video.failed
      description: 'Free. The signing secret is returned ONCE: verify X-Webhook-Signature = hex HMAC-SHA256(raw body, secret). The URL must be public https (private addresses are refused). At most 10 per account. Any valid API key works (no specific scope is checked).'
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWebhookRequest'
      responses:
        '201':
          description: Created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  webhook:
                    $ref: '#/components/schemas/Webhook'
                  secret:
                    type: string
                    description: Shown once.
                  delivery:
                    type: string
        '400':
          description: INVALID_JSON, INVALID_URL, INVALID_EVENT or INVALID_INPUT.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: WEBHOOK_LIMIT.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/webhooks/{id}:
    get:
      operationId: getWebhook
      tags:
      - Webhooks
      summary: One webhook with its recent deliveries
      description: Any valid API key works (no specific scope is checked).
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        description: Webhook id.
        schema:
          type: string
      responses:
        '200':
          description: The webhook.
          content:
            application/json:
              schema:
                type: object
                properties:
                  webhook:
                    $ref: '#/components/schemas/Webhook'
                  deliveries:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: NOT_FOUND.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      operationId: deleteWebhook
      tags:
      - Webhooks
      summary: Delete a webhook
      description: Any valid API key works (no specific scope is checked).
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        description: Webhook id.
        schema:
          type: string
      responses:
        '200':
          description: Deleted.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: NOT_FOUND.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Webhook:
      type: object
      properties:
        id:
          type: string
        url:
          type: string
        events:
          type: array
          items:
            type: string
            enum:
            - video.completed
            - video.failed
            - '*'
        description:
          type:
          - string
          - 'null'
        isActive:
          type: boolean
        lastTriggeredAt:
          type:
          - string
          - 'null'
          format: date-time
        failureCount:
          type: integer
        lastFailureAt:
          type:
          - string
          - 'null'
          format: date-time
        lastFailureReason:
          type:
          - string
          - 'null'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    CreateWebhookRequest:
      type: object
      required:
      - url
      properties:
        url:
          type: string
          description: Public https endpoint.
        events:
          type: array
          minItems: 1
          items:
            type: string
            enum:
            - video.completed
            - video.failed
            - '*'
          description: 'Default: video.completed and video.failed.'
        description:
          type: string
          maxLength: 200
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          description: Human-readable message.
        code:
          type: string
          description: Stable machine-readable code, e.g. INSUFFICIENT_CREDITS.
        details:
          type: object
          additionalProperties: true
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key (sk_live_...)
      description: AutoShort API key. Create one in the dashboard; pick the scopes the endpoints below ask for.
externalDocs:
  description: Developer portal
  url: https://autoshort.org/en/developers