Lacuna

Lacuna Music API Events

The outbound event surface of the Lacuna Music API. Lacuna publishes no AsyncAPI document; it describes its events natively in the OpenAPI 3.1 `webhooks` block — four events (job.completed, job.failed, credits.low, key.expiring) over a shared WebhookEnvelope, signed HMAC-SHA256 in X-Lacuna-Signature with a five-minute replay window. Zero request operations by design: this document is the event catalog, subscribed to from the dashboard at /profile/api.

Documentation GitHub OpenAPI

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this

find_apisBrowse and filter every API in the catalog.
get_api_artifactsOne API's artifacts, grouped by type.
get_openapiThe primary OpenAPI for this API.
find_similar_apisAPIs that look like this one.
apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
resolveTurn a domain, URL or GitHub org into the provider it belongs to.
find_cohortsEvery scored population of providers in the catalog.

All 92 tools →

Call it yourself

curl for this page

This API

curl "https://apis.io/api/v1/apis/lacuna-lacuna-music-api-api"

All apis

curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

openapi: 3.2.0
info:
  title: Lacuna Music API
  version: 0.1.0
  description: HTTP API for AI music generation.
servers:
- url: https://www.lacuna.fm/api
  description: Production
security:
- bearerAuth: []
tags:
- name: Lacuna Music API
paths: {}
webhooks:
  job.completed:
    post:
      summary: Music generation completed
      description: Sent when a task transitions to `ready` state. `tracks` contains final R2-hosted audio URLs.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JobCompletedEvent'
      responses:
        2XX:
          description: Acknowledged. Any 2xx response prevents retry.
      tags:
      - Lacuna Music API
  job.failed:
    post:
      summary: Music generation failed
      description: Sent when the task transitions to `failed`. Credits are refunded automatically.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JobFailedEvent'
      responses:
        2XX:
          description: Acknowledged.
      tags:
      - Lacuna Music API
  credits.low:
    post:
      summary: Credit balance dropped below threshold
      description: 'Edge-triggered: fires once when balance crosses below `creditAlertThreshold`. Will not re-fire until balance returns above threshold and crosses below again.'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreditsLowEvent'
      responses:
        2XX:
          description: Acknowledged.
      tags:
      - Lacuna Music API
  key.expiring:
    post:
      summary: API key expiring within 24 hours
      description: Sent once per key, 24 hours before expiry.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/KeyExpiringEvent'
      responses:
        2XX:
          description: Acknowledged.
      tags:
      - Lacuna Music API
components:
  schemas:
    JobCompletedEvent:
      allOf:
      - $ref: '#/components/schemas/WebhookEnvelope'
      - type: object
        properties:
          type:
            type: string
            enum:
            - job.completed
          data:
            type: object
            properties:
              task_id:
                type: string
              status:
                type: string
                enum:
                - ready
              tracks:
                type: array
                items:
                  $ref: '#/components/schemas/Track'
              credits_used:
                type: integer
              created_at:
                type: string
                format: date-time
    KeyExpiringEvent:
      allOf:
      - $ref: '#/components/schemas/WebhookEnvelope'
      - type: object
        properties:
          type:
            type: string
            enum:
            - key.expiring
          data:
            type: object
            properties:
              api_key_id:
                type: string
              prefix:
                type: string
              name:
                type: string
              expires_at:
                type: string
                format: date-time
              days_until_expiry:
                type: integer
    Track:
      type: object
      required:
      - id
      - audio_url
      - duration
      - title
      - lyrics
      - image_url
      - tags
      - index
      properties:
        id:
          type: string
        audio_url:
          type: string
          format: uri
        duration:
          type:
          - number
          - 'null'
          description: Seconds
        title:
          type:
          - string
          - 'null'
        lyrics:
          type:
          - string
          - 'null'
        image_url:
          type:
          - string
          - 'null'
          format: uri
        tags:
          type:
          - string
          - 'null'
        index:
          type: integer
          description: Track index within this task
    CreditsLowEvent:
      allOf:
      - $ref: '#/components/schemas/WebhookEnvelope'
      - type: object
        properties:
          type:
            type: string
            enum:
            - credits.low
          data:
            type: object
            properties:
              threshold:
                type: integer
              balance:
                type: integer
              subscription_credits:
                type: integer
              onetime_credits:
                type: integer
    JobFailedEvent:
      allOf:
      - $ref: '#/components/schemas/WebhookEnvelope'
      - type: object
        properties:
          type:
            type: string
            enum:
            - job.failed
          data:
            type: object
            properties:
              task_id:
                type: string
              status:
                type: string
                enum:
                - failed
              error:
                type: object
                properties:
                  code:
                    type: string
                  message:
                    type: string
              credits_refunded:
                type: integer
              created_at:
                type: string
                format: date-time
    WebhookEnvelope:
      type: object
      required:
      - id
      - type
      - created
      - data
      properties:
        id:
          type: string
          example: evt_abc123
        type:
          type: string
        created:
          type: integer
          description: Unix timestamp (seconds).
        data:
          type: object
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer