{
  "openapi": "3.1.0",
  "info": {
    "title": "MAP Audio Public API",
    "version": "1.1.0",
    "description": "Read-only public information from MAP Audio. These endpoints require no authentication. Customer accounts, commerce, licensing, downloads, and administration are outside this public contract.\n\nVersioning: every response carries an API-Version header (currently 1). Send the same header to pin a request; an unknown value returns HTTP 400 with an ErrorResponse. Additive changes (new fields, new endpoints) keep the version. A breaking change ships as a new version under a new URL path prefix while the previous version keeps answering. Deprecation: a retiring version or endpoint announces it with Deprecation and Sunset response headers (RFC 9745, RFC 8594) at least 90 days before removal, and the change is listed at https://map.audio/developers.",
    "contact": {
      "name": "MAP Audio support",
      "url": "https://map.audio/contact",
      "email": "support@map.audio"
    }
  },
  "servers": [
    {
      "url": "https://map.audio",
      "description": "MAP Audio public website"
    }
  ],
  "externalDocs": {
    "description": "MAP Audio developer resources",
    "url": "https://map.audio/developers"
  },
  "tags": [
    {
      "name": "Service",
      "description": "Discover the public API and its documentation."
    },
    {
      "name": "Preset packs",
      "description": "Read the public PAM preset-pack catalog."
    }
  ],
  "paths": {
    "/api/public/status": {
      "get": {
        "operationId": "getMapAudioPublicApiStatus",
        "summary": "Get MAP Audio public API status",
        "description": "Returns a small service document with links to this OpenAPI specification, developer documentation, agent guidance, and the public preset-pack catalog.",
        "tags": [
          "Service"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiVersion"
          }
        ],
        "responses": {
          "200": {
            "description": "The public API is reachable.",
            "headers": {
              "Cache-Control": {
                "description": "How long clients and shared caches may reuse the response.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Version": {
                "$ref": "#/components/headers/ApiVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StatusResponse"
                },
                "examples": {
                  "ok": {
                    "value": {
                      "service": "MAP Audio public API",
                      "status": "ok",
                      "apiVersion": "v1",
                      "documentation": "https://map.audio/developers",
                      "openapi": "https://map.audio/openapi.json",
                      "resources": {
                        "presetPacks": "https://map.audio/api/packs.json",
                        "agentGuide": "https://map.audio/llms.txt"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/UnsupportedApiVersion"
          },
          "405": {
            "$ref": "#/components/responses/MethodNotAllowed"
          }
        }
      }
    },
    "/api/packs.json": {
      "get": {
        "operationId": "listPamPresetPacks",
        "summary": "List public PAM preset packs",
        "description": "Returns the active public preset-pack catalog used by the MAP Audio website and PAM. Catalog entries can include cover and preview URLs; download URLs may still require a qualifying product or pack entitlement.",
        "tags": [
          "Preset packs"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiVersion"
          }
        ],
        "responses": {
          "200": {
            "description": "The active public PAM preset-pack catalog.",
            "headers": {
              "Cache-Control": {
                "description": "How long clients and shared caches may reuse the catalog.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Version": {
                "$ref": "#/components/headers/ApiVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PackCatalog"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/UnsupportedApiVersion"
          },
          "405": {
            "$ref": "#/components/responses/MethodNotAllowed"
          }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "ApiVersion": {
        "name": "API-Version",
        "in": "header",
        "required": false,
        "description": "Pins the request to one API version. Omit it to receive the current version. Unknown values return HTTP 400.",
        "schema": {
          "type": "string",
          "enum": [
            "1"
          ]
        }
      }
    },
    "headers": {
      "ApiVersion": {
        "description": "The API version that produced this response.",
        "schema": {
          "type": "string",
          "enum": [
            "1"
          ]
        }
      }
    },
    "responses": {
      "MethodNotAllowed": {
        "description": "The path exists, but the HTTP method is not supported.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        },
        "headers": {
          "Allow": {
            "description": "The methods this path accepts.",
            "schema": {
              "type": "string"
            }
          },
          "API-Version": {
            "$ref": "#/components/headers/ApiVersion"
          }
        }
      },
      "UnsupportedApiVersion": {
        "description": "The API-Version request header names a version this API does not serve.",
        "headers": {
          "API-Version": {
            "$ref": "#/components/headers/ApiVersion"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      }
    },
    "schemas": {
      "StatusResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "service",
          "status",
          "apiVersion",
          "documentation",
          "openapi",
          "resources"
        ],
        "properties": {
          "service": {
            "type": "string",
            "const": "MAP Audio public API"
          },
          "status": {
            "type": "string",
            "const": "ok"
          },
          "apiVersion": {
            "type": "string",
            "const": "v1"
          },
          "documentation": {
            "type": "string",
            "format": "uri"
          },
          "openapi": {
            "type": "string",
            "format": "uri"
          },
          "resources": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "presetPacks",
              "agentGuide"
            ],
            "properties": {
              "presetPacks": {
                "type": "string",
                "format": "uri"
              },
              "agentGuide": {
                "type": "string",
                "format": "uri"
              }
            }
          }
        }
      },
      "PackCatalog": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "items"
        ],
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Pack"
            }
          }
        }
      },
      "Pack": {
        "type": "object",
        "required": [
          "id",
          "name",
          "price",
          "currency",
          "currentVersion",
          "active",
          "metadata"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Stable catalog identifier."
          },
          "name": {
            "type": "string"
          },
          "tagline": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "price": {
            "type": "number",
            "minimum": 0
          },
          "currency": {
            "type": "string",
            "pattern": "^[A-Z]{3}$"
          },
          "currentVersion": {
            "type": "string"
          },
          "releasedAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          },
          "active": {
            "type": "boolean"
          },
          "featured": {
            "type": "boolean"
          },
          "freeWithPam": {
            "type": "boolean"
          },
          "bundled": {
            "type": "boolean"
          },
          "iconUrl": {
            "type": "string",
            "format": "uri"
          },
          "previewAudioUrl": {
            "type": "string",
            "format": "uri"
          },
          "downloadUrl": {
            "type": "string",
            "format": "uri"
          },
          "sizeBytes": {
            "type": "integer",
            "minimum": 0
          },
          "previewWaveform": {
            "type": "array",
            "items": {
              "type": "number",
              "minimum": 0,
              "maximum": 1
            }
          },
          "previewDuration": {
            "type": "number",
            "description": "Length of the pack preview in seconds.",
            "exclusiveMinimum": 0
          },
          "metadata": {
            "type": "object",
            "required": [
              "author"
            ],
            "properties": {
              "author": {
                "type": "string"
              },
              "authorId": {
                "type": "string"
              },
              "presetCount": {
                "type": "integer",
                "minimum": 0
              },
              "sampleCount": {
                "type": "integer",
                "minimum": 0
              },
              "tags": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "code",
              "message",
              "resolution",
              "docs"
            ],
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              },
              "resolution": {
                "type": "string"
              },
              "docs": {
                "type": "string",
                "format": "uri"
              }
            }
          }
        }
      }
    }
  }
}