{
  "openapi": "3.1.0",
  "info": {
    "title": "UrActor Academy Awards API",
    "version": "1.0.0",
    "summary": "Academy Awards data for 97 ceremonies, 1929 to 2026.",
    "description": "A free, read-only JSON API for Academy Awards nominations and winners. The API key is supplied as the final path segment rather than a header or query parameter.",
    "contact": {
      "url": "https://developer.uractor.com"
    }
  },
  "servers": [
    {
      "url": "https://api.uractor.com"
    }
  ],
  "externalDocs": {
    "url": "https://developer.uractor.com",
    "description": "Developer portal"
  },
  "paths": {
    "/oscars/apikey={apikey}": {
      "get": {
        "operationId": "allCeremonies",
        "summary": "Every ceremony from 1929 to 2026.",
        "description": "Returns the entire archive as a single object keyed by ceremony year. This is a large response — several megabytes — so prefer a narrower endpoint when you can, and cache the result if you genuinely need all of it.",
        "tags": [
          "Academy Awards"
        ],
        "parameters": [
          {
            "name": "apikey",
            "in": "path",
            "required": true,
            "description": "Your API key. Issued from the developer portal.",
            "example": "YOUR_API_KEY",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "An object whose keys are ceremony years and whose values are arrays of categories.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "403": {
            "description": "The key is missing, unknown or has been revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "More than 60 requests in a minute from one key. Wait for the number of seconds in Retry-After.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "The archive could not be read. Safe to retry.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/oscars/year={year}/apikey={apikey}": {
      "get": {
        "operationId": "ceremonyByYear",
        "summary": "Every category and nomination for one ceremony.",
        "description": "Returns the categories presented at a single ceremony, in the order they appear in the archive. This is the endpoint most applications should start with.",
        "tags": [
          "Academy Awards"
        ],
        "parameters": [
          {
            "name": "year",
            "in": "path",
            "required": true,
            "description": "Ceremony year, between 1929 and 2026. This is the year the ceremony was held, not the year the film was released.",
            "example": "2026",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "apikey",
            "in": "path",
            "required": true,
            "description": "Your API key. Issued from the developer portal.",
            "example": "YOUR_API_KEY",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "An array of category objects.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "403": {
            "description": "The key is missing, unknown or has been revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No ceremony was held in that year, or the year is outside the archive.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "More than 60 requests in a minute from one key. Wait for the number of seconds in Retry-After.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "The archive could not be read. Safe to retry.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/person/name={name}/apikey={apikey}": {
      "get": {
        "operationId": "personByName",
        "summary": "Every nomination naming a person, across all ceremonies.",
        "description": "Searches every ceremony for nominations naming this person, in either the primary or the secondary field. Matching is exact and case-sensitive, so pass the name exactly as the Academy records it. Because a film title can also appear in these fields, this endpoint doubles as a title search across all years.",
        "tags": [
          "Academy Awards"
        ],
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "required": true,
            "description": "The name to look for, URL-encoded. Matched exactly against each entry in the primary and secondary arrays.",
            "example": "Michael B. Jordan",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "apikey",
            "in": "path",
            "required": true,
            "description": "Your API key. Issued from the developer portal.",
            "example": "YOUR_API_KEY",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "An array of matches, each carrying the year and category it came from.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "403": {
            "description": "The key is missing, unknown or has been revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No person matched the values you supplied.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "More than 60 requests in a minute from one key. Wait for the number of seconds in Retry-After.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "The archive could not be read. Safe to retry.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/movie/name={name}/year={year}/apikey={apikey}": {
      "get": {
        "operationId": "filmByNameAndYear",
        "summary": "Every category a film was nominated in at a given ceremony.",
        "description": "Searches a single ceremony for nominations naming this film. Matching is exact and case-sensitive. A film usually appears in the primary field for Best Picture and in the secondary field for the craft and performance categories, so this returns both.",
        "tags": [
          "Academy Awards"
        ],
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "required": true,
            "description": "The film title, URL-encoded. Matched exactly against the primary and secondary arrays.",
            "example": "Sinners",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "year",
            "in": "path",
            "required": true,
            "description": "Ceremony year, between 1929 and 2026. This is the year the ceremony was held, not the year the film was released.",
            "example": "2026",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "apikey",
            "in": "path",
            "required": true,
            "description": "Your API key. Issued from the developer portal.",
            "example": "YOUR_API_KEY",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "An array of matches, each carrying the category it came from.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "403": {
            "description": "The key is missing, unknown or has been revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No movie matched the values you supplied.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "More than 60 requests in a minute from one key. Wait for the number of seconds in Retry-After.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "The archive could not be read. Safe to retry.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/award/name={name}/apikey={apikey}": {
      "get": {
        "operationId": "categoryByName",
        "summary": "One award category across every ceremony.",
        "description": "Returns every ceremony at which a category matching this name was presented. Unlike the person and film endpoints, matching here is a case-sensitive substring, which matters because category names have been renamed repeatedly — the leading acting award has been called both \"Best Actor in a Leading Role\" and \"Best Performance by an Actor in a Leading Role\". Searching for \"Actor in a Leading Role\" finds both.",
        "tags": [
          "Academy Awards"
        ],
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "required": true,
            "description": "The category name, URL-encoded. Matched as a substring of the full category name.",
            "example": "Actor in a Leading Role",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "apikey",
            "in": "path",
            "required": true,
            "description": "Your API key. Issued from the developer portal.",
            "example": "YOUR_API_KEY",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "An array of matches, each carrying the year and the full nomination list for that category.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "403": {
            "description": "The key is missing, unknown or has been revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No award matched the values you supplied.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "More than 60 requests in a minute from one key. Wait for the number of seconds in Retry-After.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "The archive could not be read. Safe to retry.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/award/name={name}/year={year}/apikey={apikey}": {
      "get": {
        "operationId": "categoryByNameAndYear",
        "summary": "One award category at a single ceremony.",
        "description": "The same substring matching as the previous endpoint, narrowed to one ceremony. Use this to get a category’s full slate of nominees for a given year.",
        "tags": [
          "Academy Awards"
        ],
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "required": true,
            "description": "The category name, URL-encoded. Matched as a substring of the full category name.",
            "example": "Directing",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "year",
            "in": "path",
            "required": true,
            "description": "Ceremony year, between 1929 and 2026. This is the year the ceremony was held, not the year the film was released.",
            "example": "2026",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "apikey",
            "in": "path",
            "required": true,
            "description": "Your API key. Issued from the developer portal.",
            "example": "YOUR_API_KEY",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "An array of matches, each carrying the full nomination list for that category.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "403": {
            "description": "The key is missing, unknown or has been revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No award matched the values you supplied.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "More than 60 requests in a minute from one key. Wait for the number of seconds in Retry-After.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "The archive could not be read. Safe to retry.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Nomination": {
        "type": "object",
        "properties": {
          "primary": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Who or what the nomination is for."
          },
          "secondary": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "The film, or the people sharing the award."
          },
          "won": {
            "type": "boolean"
          },
          "notes": {
            "type": "string",
            "description": "Optional historical footnote."
          }
        },
        "required": [
          "primary",
          "won"
        ]
      },
      "Category": {
        "type": "object",
        "properties": {
          "category": {
            "type": "string"
          },
          "nominations": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Nomination"
            }
          }
        },
        "required": [
          "category",
          "nominations"
        ]
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          }
        },
        "required": [
          "error"
        ]
      }
    }
  }
}