{
  "openapi": "3.0.0",
  "info": {
    "title": "YGO API: List approval links",
    "version": "2.0.0"
  },
  "servers": [
    {
      "url": "https://api.ygo.ai",
      "description": "Production and Sandbox (determined by API key)"
    }
  ],
  "paths": {
    "/v2/project/content/listApprovals": {
      "post": {
        "summary": "List approval links",
        "description": "List the calling project's approval links with their status, approver and last-opened time — the read behind an approval column in a hotel list or an approval panel on a hotel page. Pass `HotelIDs` to restrict the list to specific hotels, or omit it to page through every link of the project. Results are ordered by creation time then hotel id. Hotel ids that are not live members of the project are skipped and echoed in `NotInProjectIDs`. A link that was revoked before its hotel ever approved is excluded, from `Data` and from `Pagination.Total` alike; a link revoked after the hotel approved stays listed, carrying `RevokedAt` and no `Token`.",
        "operationId": "listApprovals",
        "tags": [
          "Content Enrichment API/Approval Links"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ListApprovalsRequest"
              },
              "examples": {
                "allLinks": {
                  "summary": "Every link of the project, first page",
                  "value": {
                    "Limit": 100,
                    "Offset": 0
                  }
                },
                "byHotelIDs": {
                  "summary": "Specific hotels, one of them not in the project",
                  "value": {
                    "HotelIDs": [
                      "019d9c2e-0ef8-7458-b0fa-8bed7182eb30",
                      "019d9c23-1238-7334-bf02-4c45c50e033a",
                      "019e4afb-e973-764c-9bb1-a4c66175e08b"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The page of approval links.",
            "headers": {
              "X-Trace-ID": {
                "$ref": "#/components/headers/X-Trace-ID"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListApprovalsResponse"
                },
                "examples": {
                  "allLinks": {
                    "summary": "Every link of the project, including one revoked after its hotel approved",
                    "value": {
                      "Data": [
                        {
                          "HotelID": "019d9c23-1238-7334-bf02-4c45c50e033a",
                          "HotelName": "JAZ Makadina",
                          "GiataID": 16706,
                          "MasterCode": "HRGD0238",
                          "TokenPreview": "QxIpAvQh...",
                          "Status": "waiting_for_hotel",
                          "Created": false,
                          "CreatedBy": "editor@example.com",
                          "CreatedAt": "2026-08-25T18:19:17.522006Z",
                          "UpdatedAt": "2026-08-25T18:19:17.522006Z"
                        },
                        {
                          "HotelID": "019d9c2e-0ef8-7458-b0fa-8bed7182eb30",
                          "HotelName": "Sotavento Beach Club",
                          "GiataID": 5721,
                          "MasterCode": "FUED0009",
                          "TokenPreview": "xPBOjXHo...",
                          "Status": "approved",
                          "ApprovedAt": "2026-08-25T18:19:18.860882Z",
                          "ApprovedTextGeneratedAt": "2026-08-19T14:14:57.674681Z",
                          "ApprovedBy": {
                            "Name": "Ayşe Yılmaz",
                            "Email": "ayse@sotavento.example",
                            "Phone": "+34 928 000 000"
                          },
                          "LastOpenedAt": "2026-08-25T18:19:18.966928Z",
                          "Created": false,
                          "CreatedBy": "editor@example.com",
                          "CreatedAt": "2026-08-25T18:19:17.522006Z",
                          "UpdatedAt": "2026-08-25T18:19:18.860882Z"
                        },
                        {
                          "HotelID": "019d9c31-77a4-7c19-9d51-2f3b8ac41e77",
                          "HotelName": "Rixos Premium Belek",
                          "GiataID": 32118,
                          "MasterCode": "AYTD0114",
                          "TokenPreview": "Lm2VrXe7...",
                          "Status": "approved",
                          "ApprovedAt": "2026-08-25T18:19:19.104553Z",
                          "ApprovedTextGeneratedAt": "2026-08-19T14:14:57.674681Z",
                          "ApprovedBy": {
                            "Name": "Mehmet Demir",
                            "Email": "mehmet@rixos.example",
                            "Phone": "+90 242 000 00 00"
                          },
                          "LastOpenedAt": "2026-08-25T18:19:19.010441Z",
                          "RevokedAt": "2026-08-25T18:19:19.602402Z",
                          "Created": false,
                          "CreatedBy": "editor@example.com",
                          "CreatedAt": "2026-08-25T18:19:17.884219Z",
                          "UpdatedAt": "2026-08-25T18:19:19.602402Z"
                        }
                      ],
                      "Pagination": {
                        "Total": 3,
                        "Limit": 100,
                        "Offset": 0
                      }
                    }
                  },
                  "byHotelIDs": {
                    "summary": "Two links, the non-member id echoed back",
                    "value": {
                      "Data": [
                        {
                          "HotelID": "019d9c23-1238-7334-bf02-4c45c50e033a",
                          "HotelName": "JAZ Makadina",
                          "GiataID": 16706,
                          "MasterCode": "HRGD0238",
                          "TokenPreview": "QxIpAvQh...",
                          "Status": "waiting_for_hotel",
                          "Created": false,
                          "CreatedBy": "editor@example.com",
                          "CreatedAt": "2026-08-25T18:19:17.522006Z",
                          "UpdatedAt": "2026-08-25T18:19:17.522006Z"
                        },
                        {
                          "HotelID": "019d9c2e-0ef8-7458-b0fa-8bed7182eb30",
                          "HotelName": "Sotavento Beach Club",
                          "GiataID": 5721,
                          "MasterCode": "FUED0009",
                          "TokenPreview": "xPBOjXHo...",
                          "Status": "approved",
                          "ApprovedAt": "2026-08-25T18:19:18.860882Z",
                          "ApprovedTextGeneratedAt": "2026-08-19T14:14:57.674681Z",
                          "ApprovedBy": {
                            "Name": "Ayşe Yılmaz",
                            "Email": "ayse@sotavento.example",
                            "Phone": "+34 928 000 000"
                          },
                          "LastOpenedAt": "2026-08-25T18:19:18.966928Z",
                          "Created": false,
                          "CreatedBy": "editor@example.com",
                          "CreatedAt": "2026-08-25T18:19:17.522006Z",
                          "UpdatedAt": "2026-08-25T18:19:18.860882Z"
                        }
                      ],
                      "Pagination": {
                        "Total": 2,
                        "Limit": 100,
                        "Offset": 0
                      },
                      "NotInProjectIDs": [
                        "019e4afb-e973-764c-9bb1-a4c66175e08b"
                      ]
                    }
                  },
                  "projectTokenCaller": {
                    "summary": "Same call with a proj_ project token — contact PII omitted: ApprovedBy carries Name only and CreatedBy is absent",
                    "value": {
                      "Data": [
                        {
                          "HotelID": "019d9c23-1238-7334-bf02-4c45c50e033a",
                          "HotelName": "JAZ Makadina",
                          "GiataID": 16706,
                          "MasterCode": "HRGD0238",
                          "TokenPreview": "QxIpAvQh...",
                          "Status": "waiting_for_hotel",
                          "Created": false,
                          "CreatedAt": "2026-08-25T18:19:17.522006Z",
                          "UpdatedAt": "2026-08-25T18:19:17.522006Z"
                        },
                        {
                          "HotelID": "019d9c2e-0ef8-7458-b0fa-8bed7182eb30",
                          "HotelName": "Sotavento Beach Club",
                          "GiataID": 5721,
                          "MasterCode": "FUED0009",
                          "TokenPreview": "xPBOjXHo...",
                          "Status": "approved",
                          "ApprovedAt": "2026-08-25T18:19:18.860882Z",
                          "ApprovedTextGeneratedAt": "2026-08-19T14:14:57.674681Z",
                          "ApprovedBy": {
                            "Name": "Ayşe Yılmaz"
                          },
                          "LastOpenedAt": "2026-08-25T18:19:18.966928Z",
                          "Created": false,
                          "CreatedAt": "2026-08-25T18:19:17.522006Z",
                          "UpdatedAt": "2026-08-25T18:19:18.860882Z"
                        }
                      ],
                      "Pagination": {
                        "Total": 2,
                        "Limit": 100,
                        "Offset": 0
                      }
                    },
                    "description": "Identical request, answered for a caller presenting a `proj_` project token instead of a `user_` token. `ApprovedBy.Email`, `ApprovedBy.Phone` and `CreatedBy` are contact PII and are omitted entirely (the keys are absent, not empty strings). Everything else is unchanged."
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/X-Project-ID"
          }
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "ApprovalApprover": {
        "type": "object",
        "required": [
          "Name"
        ],
        "properties": {
          "Name": {
            "type": "string",
            "description": "The contact's name.",
            "example": "Ayşe Yılmaz"
          },
          "Email": {
            "type": "string",
            "format": "email",
            "description": "The contact's email address.",
            "example": "ayse@sotavento.example"
          },
          "Phone": {
            "type": "string",
            "description": "The contact's phone number. Omitted when the contact did not supply one.",
            "example": "+34 928 000 000"
          }
        }
      },
      "ApprovalLink": {
        "type": "object",
        "required": [
          "HotelID",
          "HotelName",
          "TokenPreview",
          "Status",
          "Created",
          "CreatedAt",
          "UpdatedAt"
        ],
        "description": "One hotel's approval link and its state. The same shape is returned by createApprovalLinks and rotateApprovalLink (and by revokeApprovalLink, without `Token`: the link is dead). Note: this listing deliberately does not carry the full `Token` (contract A10.1) — a roster load returns up to 500 rows, and the plaintext token is a live mailable credential. Use `TokenPreview` for display; createApprovalLinks and rotateApprovalLink return the full token for the single hotel they act on.",
        "properties": {
          "HotelID": {
            "type": "string",
            "format": "uuid",
            "description": "UUID of the hotel this link belongs to.",
            "example": "019d9c2e-0ef8-7458-b0fa-8bed7182eb30"
          },
          "HotelName": {
            "type": "string",
            "description": "Display name of the hotel.",
            "example": "Sotavento Beach Club"
          },
          "GiataID": {
            "type": "integer",
            "description": "The hotel's GIATA id. Omitted when the hotel has none.",
            "example": 5721
          },
          "MasterCode": {
            "type": "string",
            "description": "The calling project's master code for this hotel. Omitted when the project has no code for it.",
            "example": "FUED0009"
          },
          "TokenPreview": {
            "type": "string",
            "description": "Display form of the token: its first 8 characters followed by an ellipsis. Never enough to reconstruct the link.",
            "example": "xPBOjXHo..."
          },
          "Status": {
            "type": "string",
            "enum": [
              "waiting_for_hotel",
              "feedback_received",
              "feedback_applied",
              "approved"
            ],
            "description": "Approval state of this hotel's link. `waiting_for_hotel` on creation; any feedback moves it to `feedback_received`; `feedback_applied` is set once the feedback has been worked in; `approved` is never left by a later feedback submission; the one way back to `waiting_for_hotel` is a re-minted link (createApprovalLinks after a revoke), which keeps ApprovedAt, ApprovedTextGeneratedAt and ApprovedBy as the record of the earlier approval.",
            "example": "waiting_for_hotel"
          },
          "ApprovedAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the hotel approved (RFC3339). Present once the hotel has ever approved: it is the RECORD of that approval and survives a later revoke and a re-minted link, so it can accompany a `waiting_for_hotel` Status (see createApprovalLinks). Only a fresh approval replaces it.",
            "example": "2026-08-25T18:19:18.860882Z"
          },
          "ApprovedTextGeneratedAt": {
            "type": "string",
            "format": "date-time",
            "description": "Newest generation timestamp across the texts that were approved (RFC3339). Compare it with the hotel's current texts to see whether they changed since the approval. Present once the hotel has ever approved (it survives a revoke and a re-minted link, like ApprovedAt), and omitted then if none of the approved texts carried a timestamp.",
            "example": "2026-08-19T14:14:57.674681Z"
          },
          "ApprovedBy": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ApprovalApprover"
              }
            ],
            "description": "Present once the hotel has ever approved: the record of who signed off, kept across a later revoke and a re-minted link (so it can accompany a `waiting_for_hotel` Status) and replaced only by a fresh approval. The identity is the snapshot taken at approval time and survives deletion of the contact record (`approved_by` is `ON DELETE SET NULL`; the snapshot columns are not cleared)."
          },
          "LastOpenedAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the approval page was last loaded (RFC3339). Omitted while the link has never been opened.",
            "example": "2026-08-25T18:19:18.966928Z"
          },
          "RevokedAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the link was revoked (RFC3339). Omitted while the link is live. A link carrying it is never returned with a `Token`.",
            "example": "2026-08-25T18:19:19.602402Z"
          },
          "Created": {
            "type": "boolean",
            "description": "`true` only when this call minted the credential in `Token`: a brand-new link, or a fresh one for a hotel whose link had been revoked. `false` for a hotel that already had a live link, and always `false` on rotateApprovalLink, revokeApprovalLink and listApprovals.",
            "example": true
          },
          "CreatedBy": {
            "type": "string",
            "description": "Audit identity of who minted the link: a user token records the user's email; a project API key records its project-scoped identity (`project:<project-uuid>`). That is what is STORED; what is RETURNED is gated. The stored identity is an operator identity by construction, so in practice it carries an internal staff email — a contact route, and therefore contact PII on the same footing as `ApprovedBy.Email` and `ApprovedBy.Phone`: it is returned only to a caller presenting a user_ token, and is omitted entirely for a proj_ project token (the key is absent, not an empty string).",
            "example": "editor@example.com"
          },
          "CreatedAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the link was minted (RFC3339).",
            "example": "2026-08-25T18:19:17.522006Z"
          },
          "UpdatedAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the link row was last touched (RFC3339). The `updated_at` trigger fires on every update, so this moves on a status transition, an approval and a token rotation — and also when the hotel merely opens the page, because that stamps `last_opened_at`. Do not use it to detect approval-state changes.",
            "example": "2026-08-25T18:19:17.522006Z"
          }
        }
      },
      "ErrorDetail": {
        "type": "object",
        "required": [
          "Code",
          "Message"
        ],
        "description": "Error detail containing a machine-readable code and human-readable message.",
        "properties": {
          "Code": {
            "type": "string",
            "description": "Machine-readable error code for programmatic handling.",
            "example": "VALIDATION_ERROR"
          },
          "Message": {
            "type": "string",
            "description": "Human-readable error message.",
            "example": "Validation failed"
          },
          "Fields": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FieldError"
            },
            "description": "Field-level validation errors. Only present for VALIDATION_ERROR responses."
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "required": [
          "Error"
        ],
        "description": "Standard v2 error response wrapper.",
        "properties": {
          "Error": {
            "$ref": "#/components/schemas/ErrorDetail"
          }
        }
      },
      "FieldError": {
        "type": "object",
        "required": [
          "Field",
          "Message"
        ],
        "description": "A single field-level validation error.",
        "properties": {
          "Field": {
            "type": "string",
            "description": "Path of the field that failed validation, as the request sends it: a dotted path for a field inside a nested request object, a bare name for a top-level one.",
            "example": "Name"
          },
          "Message": {
            "type": "string",
            "description": "Human-readable validation error message for this field.",
            "example": "Name is required"
          },
          "Code": {
            "type": "string",
            "enum": [
              "REQUIRED",
              "TOO_LONG",
              "TOO_SHORT",
              "OUT_OF_RANGE",
              "TOO_MANY",
              "INVALID_FORMAT",
              "NOT_ALLOWED",
              "CONFLICT",
              "INVALID_ENCODING",
              "INSECURE_SCHEME",
              "UNSAFE_CONTENT",
              "REQUIRED_WHEN_ENABLED"
            ],
            "description": "Machine-readable reason the field failed validation. Optional; clients should fall back to Message when it is absent or unrecognized.",
            "example": "TOO_LONG"
          },
          "Params": {
            "type": "object",
            "additionalProperties": true,
            "description": "Machine-readable values the message is built from, such as limits or allowed values. Keys are PascalCase; which keys are present depends on Code. Optional.",
            "example": {
              "Max": 200
            }
          }
        }
      },
      "ListApprovalsRequest": {
        "type": "object",
        "description": "Filter and page the project's approval links. An empty body lists every link of the project.",
        "properties": {
          "HotelIDs": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid"
            },
            "maxItems": 500,
            "description": "Restrict the list to these hotels. Optional, at most 500 entries, each a valid non-nil UUID; omit it to list every link of the project. Duplicates are collapsed.",
            "example": [
              "019d9c2e-0ef8-7458-b0fa-8bed7182eb30",
              "019d9c23-1238-7334-bf02-4c45c50e033a"
            ]
          },
          "Limit": {
            "type": "integer",
            "minimum": 0,
            "maximum": 500,
            "default": 100,
            "description": "Page size. Defaults to 100 when omitted or 0, and is capped at 500.",
            "example": 100
          },
          "Offset": {
            "type": "integer",
            "minimum": 0,
            "default": 0,
            "description": "Number of links to skip. Defaults to 0.",
            "example": 0
          }
        }
      },
      "ListApprovalsResponse": {
        "type": "object",
        "required": [
          "Data",
          "Pagination"
        ],
        "description": "List response envelope wrapping the links, plus the membership residue.",
        "properties": {
          "Data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ApprovalLink"
            },
            "description": "The project's approval links, ordered by creation time then hotel id. Always present, empty when nothing matched. Links revoked before their hotel approved are not listed."
          },
          "Pagination": {
            "$ref": "#/components/schemas/Pagination"
          },
          "NotInProjectIDs": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Requested hotel ids that are not live members of the calling project and were therefore skipped. Omitted when every requested id was a member.",
            "example": [
              "019e4afb-e973-764c-9bb1-a4c66175e08b"
            ]
          }
        }
      },
      "Pagination": {
        "type": "object",
        "required": [
          "Total",
          "Limit",
          "Offset"
        ],
        "description": "Pagination info for the list.",
        "properties": {
          "Total": {
            "type": "integer",
            "description": "Total number of links matching the request, ignoring Limit and Offset. It counts exactly the links this endpoint lists, so links revoked before their hotel approved are excluded from it too.",
            "example": 2
          },
          "Limit": {
            "type": "integer",
            "description": "Page size actually applied.",
            "example": 100
          },
          "Offset": {
            "type": "integer",
            "description": "Offset actually applied.",
            "example": 0
          }
        }
      }
    },
    "parameters": {
      "X-Project-ID": {
        "name": "X-Project-ID",
        "in": "header",
        "required": true,
        "description": "Project UUID. Required for all project-scoped endpoints.",
        "example": "$YGO_PROJECT_ID",
        "schema": {
          "type": "string",
          "format": "uuid"
        }
      }
    },
    "headers": {
      "Retry-After": {
        "description": "Number of seconds to wait before retrying the request. Present on 429 responses.",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "example": 39
        }
      },
      "X-Trace-ID": {
        "description": "Request trace ID for debugging (OpenTelemetry). Include this ID when contacting support about specific requests.",
        "schema": {
          "type": "string",
          "example": "abc123def456ghi789"
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Bad Request - the request body or the X-Project-ID header failed validation.",
        "headers": {
          "X-Trace-ID": {
            "$ref": "#/components/headers/X-Trace-ID"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "missingProjectHeader": {
                "summary": "X-Project-ID header missing",
                "value": {
                  "Error": {
                    "Code": "VALIDATION_ERROR",
                    "Message": "X-Project-ID header is required"
                  }
                }
              },
              "invalidBody": {
                "summary": "Malformed request body",
                "value": {
                  "Error": {
                    "Code": "VALIDATION_ERROR",
                    "Message": "Invalid request body"
                  }
                }
              },
              "negativePaging": {
                "summary": "Limit or Offset is negative",
                "value": {
                  "Error": {
                    "Code": "VALIDATION_ERROR",
                    "Message": "Validation failed",
                    "Fields": [
                      {
                        "Field": "Limit",
                        "Message": "Limit and Offset must not be negative"
                      }
                    ]
                  }
                }
              },
              "tooManyHotelIDs": {
                "summary": "More than 500 entries in HotelIDs",
                "value": {
                  "Error": {
                    "Code": "VALIDATION_ERROR",
                    "Message": "Validation failed",
                    "Fields": [
                      {
                        "Field": "HotelIDs",
                        "Message": "HotelIDs may contain at most 500 entries"
                      }
                    ]
                  }
                }
              },
              "invalidHotelID": {
                "summary": "An entry in HotelIDs is not a valid UUID",
                "value": {
                  "Error": {
                    "Code": "VALIDATION_ERROR",
                    "Message": "Validation failed",
                    "Fields": [
                      {
                        "Field": "HotelIDs",
                        "Message": "HotelIDs must contain valid UUIDs"
                      }
                    ]
                  }
                }
              }
            }
          }
        }
      },
      "Forbidden": {
        "description": "Forbidden - the caller is authenticated but may not act on this project. Also returned with code INSUFFICIENT_SCOPE when the API key does not carry the content.authoring:read permission this endpoint requires.",
        "headers": {
          "X-Trace-ID": {
            "$ref": "#/components/headers/X-Trace-ID"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "insufficientScope": {
                "summary": "Missing required scope",
                "value": {
                  "Error": {
                    "Code": "INSUFFICIENT_SCOPE",
                    "Message": "token lacks scope content.authoring:read"
                  }
                }
              },
              "accessDenied": {
                "summary": "The user token has no editor access to the project",
                "value": {
                  "Error": {
                    "Code": "FORBIDDEN",
                    "Message": "Access denied to project"
                  }
                }
              },
              "noProjectScope": {
                "summary": "The request carries no project scope",
                "value": {
                  "Error": {
                    "Code": "FORBIDDEN",
                    "Message": "Project access required"
                  }
                }
              }
            }
          }
        }
      },
      "InternalServerError": {
        "description": "Internal Server Error - Unexpected server error. Include the X-Trace-ID header value when contacting support.",
        "headers": {
          "X-Trace-ID": {
            "$ref": "#/components/headers/X-Trace-ID"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "listFailed": {
                "summary": "The links could not be listed",
                "value": {
                  "Error": {
                    "Code": "INTERNAL_ERROR",
                    "Message": "Failed to list approval links"
                  }
                }
              },
              "membershipFailed": {
                "summary": "Hotel membership could not be verified",
                "value": {
                  "Error": {
                    "Code": "INTERNAL_ERROR",
                    "Message": "Failed to verify hotels"
                  }
                }
              }
            }
          }
        }
      },
      "NotFound": {
        "description": "Not Found - the project or the hotel is not reachable for this caller.",
        "headers": {
          "X-Trace-ID": {
            "$ref": "#/components/headers/X-Trace-ID"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "projectNotFound": {
                "summary": "The project does not exist or was deleted (user tokens)",
                "value": {
                  "Error": {
                    "Code": "NOT_FOUND",
                    "Message": "Project not found"
                  }
                }
              }
            }
          }
        }
      },
      "TooManyRequests": {
        "description": "Too Many Requests. The response includes a `Retry-After` header with the number of seconds to wait before retrying.",
        "headers": {
          "X-Trace-ID": {
            "$ref": "#/components/headers/X-Trace-ID"
          },
          "Retry-After": {
            "$ref": "#/components/headers/Retry-After"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "rateLimited": {
                "summary": "Limit exceeded",
                "value": {
                  "Error": {
                    "Code": "RATE_LIMIT_EXCEEDED",
                    "Message": "Rate limit exceeded. Retry after the number of seconds in the Retry-After header."
                  }
                }
              }
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Unauthorized - Invalid or missing bearer token.",
        "headers": {
          "X-Trace-ID": {
            "$ref": "#/components/headers/X-Trace-ID"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "missingToken": {
                "summary": "No Authorization header",
                "value": {
                  "Error": {
                    "Code": "UNAUTHORIZED",
                    "Message": "Missing bearer token"
                  }
                }
              },
              "invalidToken": {
                "summary": "The bearer token is not valid",
                "value": {
                  "Error": {
                    "Code": "UNAUTHORIZED",
                    "Message": "Invalid bearer token"
                  }
                }
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Project-scoped API key"
      }
    }
  }
}
