{
  "openapi": "3.0.0",
  "info": {
    "version": "1.0.0",
    "title": "Gondola Public Credit Lookup API",
    "description": "Find the public credits recorded on Gondola for a social media post.\nFree and read-only; no account, key, MCP connection, or skill is required.\nUse the full post permalink. Redirects are not followed, and unknown posts\nare not scraped or imported. Supports Instagram, TikTok, X, YouTube,\nFacebook, LinkedIn, and Threads.\n\nCredits record roles on Gondola, not verified authorship or ownership.\nA brand, account owner, or featured person is not necessarily the creator.\nCite post.gondolaUrl and preserve the role when reporting a credit.\nA missing record or empty credit list does not prove that no creator exists.\nPrivate credits and hidden identities are never returned, even with a session.\nurl is the only query parameter. Other query parameters are ignored.\nCache results for five minutes; this endpoint does not provide bulk search.\n\nLimits are 30 requests per minute and 300 per hour per IP address (IPv6 /64),\nshared across all Gondola servers. Invalid requests count toward these limits.\nHTTP 429 includes Retry-After in seconds; wait before retrying.\nX-RateLimit-Limit and X-RateLimit-Remaining describe the most constrained window.\nX-RateLimit-Reset is the number of seconds until that window resets.\nResponses are not stored in shared HTTP caches so limits apply at the origin;\nclients can cache lookup data for five minutes to avoid repeated requests.\nRequest logs include a pseudonymous IP hash, user agent, normalized source URL,\noutcome, HTTP status, and duration. Logs are cleaned up after 30 days.\nRejected requests are not written to the database; throttling events are logged separately.\n"
  },
  "servers": [
    {
      "url": "https://gondola.cc"
    }
  ],
  "security": [],
  "paths": {
    "/api/v1/credits": {
      "get": {
        "operationId": "lookupPublicCredits",
        "summary": "Look up credits by social post URL",
        "parameters": [
          {
            "name": "url",
            "in": "query",
            "required": true,
            "description": "Full social post permalink, URL-encoded as a query parameter.",
            "schema": {
              "type": "string",
              "maxLength": 2048
            },
            "example": "https://www.instagram.com/p/ClJqVDBtRsq"
          }
        ],
        "responses": {
          "200": {
            "description": "Lookup completed; check data.status for coverage.",
            "headers": {
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/Remaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "success",
                    "error",
                    "data"
                  ],
                  "properties": {
                    "success": {
                      "type": "integer",
                      "enum": [
                        1
                      ]
                    },
                    "error": {
                      "type": "integer",
                      "enum": [
                        0
                      ]
                    },
                    "data": {
                      "type": "object",
                      "required": [
                        "status",
                        "sourceUrl",
                        "post",
                        "credits"
                      ],
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": [
                            "found",
                            "no_public_credits",
                            "not_found"
                          ],
                          "example": "found"
                        },
                        "sourceUrl": {
                          "type": "string",
                          "description": "Stored original post URL, or normalized input when not found.",
                          "example": "https://www.instagram.com/p/ClJqVDBtRsq"
                        },
                        "post": {
                          "type": "object",
                          "nullable": true,
                          "required": [
                            "gondolaUrl",
                            "network",
                            "account",
                            "postedAt"
                          ],
                          "properties": {
                            "gondolaUrl": {
                              "type": "string",
                              "format": "uri",
                              "description": "Cite this page as the source of the credits.",
                              "example": "https://gondola.cc/posts/2690540-leomessi-instagram"
                            },
                            "network": {
                              "type": "string",
                              "example": "instagram"
                            },
                            "account": {
                              "type": "string",
                              "nullable": true,
                              "example": "leomessi"
                            },
                            "postedAt": {
                              "type": "string",
                              "format": "date-time",
                              "nullable": true,
                              "example": "2022-11-19T17:30:06.000Z"
                            }
                          }
                        },
                        "credits": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "required": [
                              "name",
                              "username",
                              "profileUrl",
                              "role"
                            ],
                            "properties": {
                              "name": {
                                "type": "string",
                                "example": "Annie Leibovitz"
                              },
                              "username": {
                                "type": "string",
                                "nullable": true,
                                "example": "annieleibovitz"
                              },
                              "profileUrl": {
                                "type": "string",
                                "format": "uri",
                                "nullable": true,
                                "example": "https://gondola.cc/annieleibovitz"
                              },
                              "role": {
                                "type": "string",
                                "description": "The role credited on this post, not a default profile role.",
                                "example": "Photographer"
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                },
                "examples": {
                  "found": {
                    "summary": "Photographer, brand, and featured talent credited on an Instagram post",
                    "description": "Example based on the Gondola record for the Messi and Ronaldo Louis Vuitton\nphotograph. Preserve the recorded roles; the featured players and brand are\nnot being identified as the photographer. Live credits can change.\n",
                    "value": {
                      "success": 1,
                      "error": 0,
                      "data": {
                        "status": "found",
                        "sourceUrl": "https://www.instagram.com/p/ClJqVDBtRsq",
                        "post": {
                          "gondolaUrl": "https://gondola.cc/posts/2690540-leomessi-instagram",
                          "network": "instagram",
                          "account": "leomessi",
                          "postedAt": "2022-11-19T17:30:06.000Z"
                        },
                        "credits": [
                          {
                            "name": "Louis Vuitton",
                            "username": "LouisVuitton",
                            "profileUrl": "https://gondola.cc/LouisVuitton",
                            "role": "Brand"
                          },
                          {
                            "name": "Cristiano Ronaldo",
                            "username": "Cristiano",
                            "profileUrl": "https://gondola.cc/Cristiano",
                            "role": "Professional Soccer Player"
                          },
                          {
                            "name": "Leo Messi",
                            "username": "leomessi",
                            "profileUrl": "https://gondola.cc/leomessi",
                            "role": "Professional Soccer Player"
                          },
                          {
                            "name": "Annie Leibovitz",
                            "username": "annieleibovitz",
                            "profileUrl": "https://gondola.cc/annieleibovitz",
                            "role": "Photographer"
                          }
                        ]
                      }
                    }
                  },
                  "noPublicCredits": {
                    "summary": "Post found, but no public credits are available",
                    "description": "Illustrative record showing an empty public credit list.",
                    "value": {
                      "success": 1,
                      "error": 0,
                      "data": {
                        "status": "no_public_credits",
                        "sourceUrl": "https://www.youtube.com/watch?v=J8aV7H2rQ4s",
                        "post": {
                          "gondolaUrl": "https://gondola.cc/posts/18240567-harborstudio-youtube",
                          "network": "youtube",
                          "account": "harborstudio",
                          "postedAt": "2026-10-20T14:30:00.000Z"
                        },
                        "credits": []
                      }
                    }
                  },
                  "notFound": {
                    "summary": "Social post has no matching Gondola record",
                    "description": "Illustrative lookup miss; it does not establish who made the post.",
                    "value": {
                      "success": 1,
                      "error": 0,
                      "data": {
                        "status": "not_found",
                        "sourceUrl": "https://tiktok.com/@harborstudio/video/7482136549870124321",
                        "post": null,
                        "credits": []
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing, repeated, invalid, or unsupported post URL. The message says what was wrong and how to send the request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": 0,
                  "error": 1,
                  "message": "The required url query parameter is missing. Send the full permalink of one Instagram, TikTok, X, YouTube, Facebook, LinkedIn, or Threads post, URL-encoded, in the url query parameter. Example: GET https://gondola.cc/api/v1/credits?url=https%3A%2F%2Fwww.instagram.com%2Fp%2FClJqVDBtRsq Docs: https://gondola.cc/docs/api/credits",
                  "errorType": 0
                }
              }
            }
          },
          "429": {
            "description": "IP allowance exceeded. Wait Retry-After seconds before retrying.",
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/Reset"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/Limit"
              },
              "X-RateLimit-Remaining": {
                "description": "No requests remain in the exhausted window.",
                "schema": {
                  "type": "integer",
                  "enum": [
                    0
                  ],
                  "example": 0
                }
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": 0,
                  "error": 1,
                  "message": "Public credit lookup rate limit exceeded",
                  "errorType": 0
                }
              }
            }
          },
          "500": {
            "description": "Lookup could not be completed. Retry later; do not infer missing credits.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": 0,
                  "error": 1,
                  "message": "An unexpected error occurred",
                  "errorType": 0
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "required": [
          "success",
          "error",
          "message",
          "errorType"
        ],
        "properties": {
          "success": {
            "type": "integer",
            "enum": [
              0
            ]
          },
          "error": {
            "type": "integer",
            "enum": [
              1
            ]
          },
          "message": {
            "type": "string",
            "example": "Public credit lookup rate limit exceeded"
          },
          "errorType": {
            "type": "integer",
            "example": 0
          }
        }
      }
    },
    "headers": {
      "Limit": {
        "description": "Maximum requests in the reported rate limit window.",
        "schema": {
          "type": "integer",
          "example": 30
        }
      },
      "Remaining": {
        "description": "Requests remaining in the reported window.",
        "schema": {
          "type": "integer",
          "minimum": 0,
          "example": 29
        }
      },
      "Reset": {
        "description": "Seconds until the reported rate limit window resets.",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "example": 60
        }
      }
    }
  }
}