{
  "openapi": "3.1.0",
  "info": {
    "title": "AudioGist Read-only API",
    "version": "1.0.0",
    "description": "Read completed and in-progress transcripts owned by the AudioGist user who created the API key. The API is intentionally read-only and requires a Basic, Standard, or Pro entitlement."
  },
  "servers": [
    {
      "url": "https://api-staging.knovox.com",
      "description": "AudioGist API origin for this build."
    }
  ],
  "tags": [
    {
      "name": "Transcripts",
      "description": "Read-only access to transcript metadata and content."
    }
  ],
  "security": [
    {
      "ApiKeyBearer": []
    }
  ],
  "paths": {
    "/api/v1/transcripts": {
      "get": {
        "operationId": "listTranscripts",
        "summary": "List transcripts",
        "description": "Returns transcripts owned by the API key user. Results are ordered by the service repository and use offset pagination.",
        "tags": [
          "Transcripts"
        ],
        "x-audiogist-scope": "transcripts:read",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of transcripts to return.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25
            }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "Number of transcripts to skip. The current maximum is 10,000.",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 10000,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Transcript page",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TranscriptListResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/InvalidApiKey"
          },
          "403": {
            "$ref": "#/components/responses/InsufficientScope"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/api/v1/transcripts/{id}": {
      "get": {
        "operationId": "getTranscript",
        "summary": "Get transcript content",
        "description": "Returns one transcript with segments, structured summary data, and action items. A transcript owned by another user is returned as not found.",
        "tags": [
          "Transcripts"
        ],
        "x-audiogist-scope": "transcripts:read",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "AudioGist transcript ID.",
            "schema": {
              "type": "string",
              "pattern": "^tr_[A-Za-z0-9]+$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Transcript content",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TranscriptDetailResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/InvalidApiKey"
          },
          "403": {
            "$ref": "#/components/responses/InsufficientScope"
          },
          "404": {
            "$ref": "#/components/responses/TranscriptNotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyBearer": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "AudioGist API key",
        "description": "Use the complete ag_live_... key shown once when it is created. Cookie sessions are not accepted by /api/v1 endpoints."
      }
    },
    "headers": {
      "RequestId": {
        "description": "Safe request identifier for support and log correlation.",
        "schema": {
          "type": "string"
        }
      },
      "RetryAfter": {
        "description": "Seconds until the current API-key rate-limit window permits another request.",
        "schema": {
          "type": "integer",
          "minimum": 1
        }
      }
    },
    "responses": {
      "ValidationError": {
        "description": "Invalid pagination parameters",
        "headers": {
          "X-Request-Id": {
            "$ref": "#/components/headers/RequestId"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "error": {
                "code": "VALIDATION_ERROR",
                "message": "Developer API pagination parameters are invalid.",
                "details": {
                  "limit": [
                    "Invalid value"
                  ]
                },
                "requestId": "request-id"
              }
            }
          }
        }
      },
      "InvalidApiKey": {
        "description": "API key is missing, malformed, forged, expired, revoked, or no longer backed by a paid entitlement",
        "headers": {
          "X-Request-Id": {
            "$ref": "#/components/headers/RequestId"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "InsufficientScope": {
        "description": "The key does not contain transcripts:read",
        "headers": {
          "X-Request-Id": {
            "$ref": "#/components/headers/RequestId"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "TranscriptNotFound": {
        "description": "Transcript does not exist or is not owned by the API key user",
        "headers": {
          "X-Request-Id": {
            "$ref": "#/components/headers/RequestId"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "RateLimited": {
        "description": "Per-key limit exceeded",
        "headers": {
          "X-Request-Id": {
            "$ref": "#/components/headers/RequestId"
          },
          "Retry-After": {
            "$ref": "#/components/headers/RetryAfter"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "InternalError": {
        "description": "Unexpected internal error. The response is sanitized and includes a request ID for support correlation.",
        "headers": {
          "X-Request-Id": {
            "$ref": "#/components/headers/RequestId"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "ServiceUnavailable": {
        "description": "The API runtime or one of its required bindings is not ready to serve requests.",
        "headers": {
          "X-Request-Id": {
            "$ref": "#/components/headers/RequestId"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      }
    },
    "schemas": {
      "Transcript": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "title",
          "source",
          "status",
          "durationSeconds",
          "language",
          "summaryLanguage",
          "speakerCount",
          "progress",
          "summaryTemplateKey",
          "queuedAt",
          "completedAt",
          "createdAt",
          "updatedAt"
        ],
        "properties": {
          "id": {
            "type": "string",
            "examples": [
              "tr_0123456789ab"
            ]
          },
          "title": {
            "type": "string"
          },
          "source": {
            "type": "string",
            "enum": [
              "upload",
              "record",
              "youtube"
            ]
          },
          "sourceUrl": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          },
          "status": {
            "type": "string",
            "enum": [
              "queued",
              "processing",
              "completed",
              "failed"
            ]
          },
          "durationSeconds": {
            "type": "integer",
            "minimum": 0
          },
          "language": {
            "type": "string"
          },
          "summaryLanguage": {
            "type": "string",
            "description": "Requested summary output language. auto follows the detected transcript language."
          },
          "speakerCount": {
            "type": "integer",
            "minimum": 0
          },
          "progress": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100
          },
          "summaryTemplateKey": {
            "type": "string"
          },
          "queuedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "completedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Segment": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "position",
          "startMs",
          "endMs",
          "speakerKey",
          "speakerLabel",
          "text",
          "confidence"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "position": {
            "type": "integer",
            "minimum": 0
          },
          "startMs": {
            "type": "integer",
            "minimum": 0
          },
          "endMs": {
            "type": "integer",
            "minimum": 0
          },
          "speakerKey": {
            "type": [
              "string",
              "null"
            ],
            "description": "Stable diarization identity when the transcription provider supplies one."
          },
          "speakerLabel": {
            "type": [
              "string",
              "null"
            ],
            "description": "Human-readable speaker label when one is available."
          },
          "text": {
            "type": "string"
          },
          "confidence": {
            "type": [
              "number",
              "null"
            ],
            "minimum": 0,
            "maximum": 1
          }
        }
      },
      "NotableQuote": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "text"
        ],
        "properties": {
          "text": {
            "type": "string"
          },
          "speaker": {
            "type": "string"
          },
          "timestamp": {
            "type": "string",
            "description": "Source position formatted as MM:SS or HH:MM:SS when available."
          }
        }
      },
      "Chapter": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "title",
          "summary",
          "timestamp"
        ],
        "properties": {
          "title": {
            "type": "string"
          },
          "summary": {
            "type": "string"
          },
          "timestamp": {
            "type": "string",
            "description": "Chapter start position formatted as MM:SS or HH:MM:SS."
          }
        }
      },
      "SummaryContent": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "overview": {
            "type": "string"
          },
          "keyPoints": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "keywords": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "decisions": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "chapters": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Chapter"
            }
          },
          "notableQuotes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/NotableQuote"
            }
          }
        }
      },
      "Summary": {
        "type": [
          "object",
          "null"
        ],
        "additionalProperties": false,
        "required": [
          "id",
          "templateKey",
          "content",
          "model"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "templateKey": {
            "type": "string"
          },
          "content": {
            "$ref": "#/components/schemas/SummaryContent"
          },
          "model": {
            "type": "string"
          }
        }
      },
      "ActionItem": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "content",
          "owner",
          "completed"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "content": {
            "type": "string"
          },
          "owner": {
            "type": [
              "string",
              "null"
            ]
          },
          "completed": {
            "type": "boolean"
          }
        }
      },
      "Pagination": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "limit",
          "offset",
          "hasMore"
        ],
        "properties": {
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100
          },
          "offset": {
            "type": "integer",
            "minimum": 0,
            "maximum": 10000
          },
          "hasMore": {
            "type": "boolean"
          }
        }
      },
      "TranscriptListResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "data",
          "pagination"
        ],
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Transcript"
            }
          },
          "pagination": {
            "$ref": "#/components/schemas/Pagination"
          }
        }
      },
      "TranscriptDetail": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "transcript",
          "insightsStale",
          "segments",
          "summary",
          "actionItems"
        ],
        "properties": {
          "transcript": {
            "$ref": "#/components/schemas/Transcript"
          },
          "insightsStale": {
            "type": "boolean",
            "description": "True when the transcript changed after insight generation or a replacement summary is still running. Stale summaries and action items are omitted."
          },
          "segments": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Segment"
            }
          },
          "summary": {
            "$ref": "#/components/schemas/Summary"
          },
          "actionItems": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ActionItem"
            }
          }
        }
      },
      "TranscriptDetailResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "data"
        ],
        "properties": {
          "data": {
            "$ref": "#/components/schemas/TranscriptDetail"
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "code",
          "message",
          "requestId"
        ],
        "properties": {
          "code": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "requestId": {
            "type": "string"
          },
          "retryAfterSeconds": {
            "type": "integer",
            "minimum": 1
          },
          "action": {
            "type": "string"
          },
          "details": {
            "type": "object",
            "additionalProperties": true
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}