{"components":{"responses":{"InvalidAgentPass":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The Agent Pass is invalid, revoked, expired or does not permit this resource."},"InvalidApiKey":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The supplied API key is invalid or revoked."},"NotFound":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The horse or requested dataset was not found."},"PaymentRequired":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The available credit allowance is insufficient."},"RateLimited":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The request-rate limit was exceeded."}},"schemas":{"Access":{"properties":{"agent_pass":{"type":"boolean"},"anonymous":{"type":"boolean"},"cost_credits":{"minimum":0,"type":"integer"}},"required":["cost_credits","anonymous","agent_pass"],"type":"object"},"BasicHorse":{"additionalProperties":true,"properties":{"access":{"$ref":"#/components/schemas/Access"},"career":{"additionalProperties":true,"type":"object"},"id":{"type":"string"},"name":{"type":"string"},"profile_url":{"format":"uri","type":"string"},"schema_version":{"type":"string"},"slug":{"type":"string"},"structured_access":{"$ref":"#/components/schemas/StructuredAccessUpgrade"},"type":{"const":"horse"},"uma":{"additionalProperties":true,"type":"object"}},"required":["schema_version","type","id","slug","name","access"],"type":"object"},"CompleteProfile":{"allOf":[{"$ref":"#/components/schemas/BasicHorse"},{"properties":{"availability":{"additionalProperties":{"enum":["available","partial","unavailable"]},"type":"object"},"datasets":{"additionalProperties":true,"required":["uma","irl","races"],"type":"object"},"type":{"const":"complete_profile"}},"required":["datasets","availability"],"type":"object"}]},"DatasetEnvelope":{"additionalProperties":true,"properties":{"access":{"$ref":"#/components/schemas/Access"},"availability":{"enum":["available","partial","unavailable"]},"data":{"additionalProperties":true,"type":"object"},"dataset":{"enum":["uma","irl","races"]},"schema_version":{"type":"string"},"slug":{"type":"string"},"sources":{"items":{"type":"object"},"type":"array"},"type":{"pattern":"_dataset$","type":"string"}},"required":["schema_version","type","slug","dataset","availability","data","sources","access"],"type":"object"},"Error":{"additionalProperties":true,"properties":{"available_credits":{"type":"integer"},"error":{"type":"string"},"message":{"type":"string"},"register_url":{"format":"uri","type":"string"},"required_credits":{"type":"integer"}},"required":["error"],"type":"object"},"StructuredAccessUpgrade":{"properties":{"agent_passes":{"additionalProperties":true,"type":"object"},"credit_value_gbp":{"const":"0.01"},"current_tier":{"properties":{"cost_credits":{"const":2},"id":{"const":"basic"},"label":{"type":"string"},"price_gbp":{"const":"0.02"}},"required":["id","cost_credits","price_gbp"],"type":"object"},"note":{"type":"string"},"openapi_url":{"format":"uri","type":"string"},"pricing_url":{"format":"uri","type":"string"},"upgrade_options":{"items":{"properties":{"cost_credits":{"enum":[5,10]},"description":{"type":"string"},"id":{"enum":["uma","irl","races","complete"]},"label":{"type":"string"},"price_gbp":{"enum":["0.05","0.10"]},"url":{"format":"uri","type":"string"}},"required":["id","label","description","cost_credits","price_gbp","url"],"type":"object"},"minItems":4,"type":"array"}},"required":["current_tier","upgrade_options","credit_value_gbp"],"type":"object"}},"securitySchemes":{"ApiKeyAuth":{"in":"header","name":"X-API-Key","type":"apiKey"},"BearerAuth":{"bearerFormat":"uma_sk_...","description":"Send a registered UmaArchive API key as a Bearer token.","scheme":"bearer","type":"http"}}},"externalDocs":{"description":"Developer registration, keys and credit purchases","url":"https://umaarchive.com/developers/"},"info":{"description":"Paid access to clean, stable, machine-readable Uma Musume, real-horse and race data. Public website browsing remains free. Anonymous API clients receive a small daily allowance.","title":"UmaArchive Structured Access API","version":"1.3"},"openapi":"3.1.0","paths":{"/api/v1":{"get":{"operationId":"discoverStructuredAccess","responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":true,"type":"object"}}},"description":"Free API discovery document."}},"security":[],"summary":"Discover Structured Access endpoints and prices","tags":["Discovery"],"x-credit-cost":0}},"/api/v1/agent/{agent_pass_token}":{"get":{"operationId":"discoverAgentPass","parameters":[{"description":"Short-lived prepaid Agent Pass token embedded in a capability URL.","in":"path","name":"agent_pass_token","required":true,"schema":{"pattern":"^uma_ap_[A-Za-z0-9_-]+$","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":true,"type":"object"}}},"description":"Active pass metadata, remaining balance, restrictions and endpoint URLs."},"401":{"$ref":"#/components/responses/InvalidAgentPass"},"403":{"$ref":"#/components/responses/InvalidAgentPass"},"410":{"$ref":"#/components/responses/InvalidAgentPass"}},"security":[],"summary":"Inspect an Agent Pass and discover its tokenised endpoints","tags":["Agent Passes"],"x-credit-cost":0}},"/api/v1/agent/{agent_pass_token}/umas/{slug}":{"get":{"description":"No request headers are required. The capability URL pays from its reserved balance.","operationId":"getBasicHorseWithAgentPass","parameters":[{"description":"Short-lived prepaid Agent Pass token embedded in a capability URL.","in":"path","name":"agent_pass_token","required":true,"schema":{"pattern":"^uma_ap_[A-Za-z0-9_-]+$","type":"string"}},{"description":"Stable UmaArchive horse slug.","example":"special-week","in":"path","name":"slug","required":true,"schema":{"pattern":"^[a-z0-9-]+$","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BasicHorse"}}},"description":"Successful response; costs 2 credits.","headers":{"X-Agent-Pass-Remaining":{"schema":{"type":"integer"}},"X-Credits-Remaining":{"schema":{"type":"integer"}},"X-Request-Id":{"schema":{"type":"string"}},"X-Schema-Version":{"schema":{"type":"string"}},"X-Usage-Cost":{"schema":{"type":"integer"}}}},"401":{"$ref":"#/components/responses/InvalidAgentPass"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/InvalidAgentPass"},"404":{"$ref":"#/components/responses/NotFound"},"410":{"$ref":"#/components/responses/InvalidAgentPass"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[],"summary":"Get a basic horse lookup using an Agent Pass","tags":["Structured profiles"],"x-credit-cost":2}},"/api/v1/agent/{agent_pass_token}/umas/{slug}/complete":{"get":{"description":"No request headers are required. The capability URL pays from its reserved balance.","operationId":"getCompleteProfileWithAgentPass","parameters":[{"description":"Short-lived prepaid Agent Pass token embedded in a capability URL.","in":"path","name":"agent_pass_token","required":true,"schema":{"pattern":"^uma_ap_[A-Za-z0-9_-]+$","type":"string"}},{"description":"Stable UmaArchive horse slug.","example":"special-week","in":"path","name":"slug","required":true,"schema":{"pattern":"^[a-z0-9-]+$","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompleteProfile"}}},"description":"Successful response; costs 10 credits.","headers":{"X-Agent-Pass-Remaining":{"schema":{"type":"integer"}},"X-Credits-Remaining":{"schema":{"type":"integer"}},"X-Request-Id":{"schema":{"type":"string"}},"X-Schema-Version":{"schema":{"type":"string"}},"X-Usage-Cost":{"schema":{"type":"integer"}}}},"401":{"$ref":"#/components/responses/InvalidAgentPass"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/InvalidAgentPass"},"404":{"$ref":"#/components/responses/NotFound"},"410":{"$ref":"#/components/responses/InvalidAgentPass"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[],"summary":"Get a complete profile using an Agent Pass","tags":["Structured profiles"],"x-credit-cost":10}},"/api/v1/agent/{agent_pass_token}/umas/{slug}/irl":{"get":{"description":"No request headers are required. The capability URL pays from its reserved balance.","operationId":"getIrlDatasetWithAgentPass","parameters":[{"description":"Short-lived prepaid Agent Pass token embedded in a capability URL.","in":"path","name":"agent_pass_token","required":true,"schema":{"pattern":"^uma_ap_[A-Za-z0-9_-]+$","type":"string"}},{"description":"Stable UmaArchive horse slug.","example":"special-week","in":"path","name":"slug","required":true,"schema":{"pattern":"^[a-z0-9-]+$","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatasetEnvelope"}}},"description":"Successful response; costs 5 credits.","headers":{"X-Agent-Pass-Remaining":{"schema":{"type":"integer"}},"X-Credits-Remaining":{"schema":{"type":"integer"}},"X-Request-Id":{"schema":{"type":"string"}},"X-Schema-Version":{"schema":{"type":"string"}},"X-Usage-Cost":{"schema":{"type":"integer"}}}},"401":{"$ref":"#/components/responses/InvalidAgentPass"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/InvalidAgentPass"},"404":{"$ref":"#/components/responses/NotFound"},"410":{"$ref":"#/components/responses/InvalidAgentPass"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[],"summary":"Get real-horse data using an Agent Pass","tags":["Structured profiles"],"x-credit-cost":5}},"/api/v1/agent/{agent_pass_token}/umas/{slug}/races":{"get":{"description":"No request headers are required. The capability URL pays from its reserved balance.","operationId":"getRaceDatasetWithAgentPass","parameters":[{"description":"Short-lived prepaid Agent Pass token embedded in a capability URL.","in":"path","name":"agent_pass_token","required":true,"schema":{"pattern":"^uma_ap_[A-Za-z0-9_-]+$","type":"string"}},{"description":"Stable UmaArchive horse slug.","example":"special-week","in":"path","name":"slug","required":true,"schema":{"pattern":"^[a-z0-9-]+$","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatasetEnvelope"}}},"description":"Successful response; costs 5 credits.","headers":{"X-Agent-Pass-Remaining":{"schema":{"type":"integer"}},"X-Credits-Remaining":{"schema":{"type":"integer"}},"X-Request-Id":{"schema":{"type":"string"}},"X-Schema-Version":{"schema":{"type":"string"}},"X-Usage-Cost":{"schema":{"type":"integer"}}}},"401":{"$ref":"#/components/responses/InvalidAgentPass"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/InvalidAgentPass"},"404":{"$ref":"#/components/responses/NotFound"},"410":{"$ref":"#/components/responses/InvalidAgentPass"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[],"summary":"Get race data using an Agent Pass","tags":["Structured profiles"],"x-credit-cost":5}},"/api/v1/agent/{agent_pass_token}/umas/{slug}/uma":{"get":{"description":"No request headers are required. The capability URL pays from its reserved balance.","operationId":"getUmaDatasetWithAgentPass","parameters":[{"description":"Short-lived prepaid Agent Pass token embedded in a capability URL.","in":"path","name":"agent_pass_token","required":true,"schema":{"pattern":"^uma_ap_[A-Za-z0-9_-]+$","type":"string"}},{"description":"Stable UmaArchive horse slug.","example":"special-week","in":"path","name":"slug","required":true,"schema":{"pattern":"^[a-z0-9-]+$","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatasetEnvelope"}}},"description":"Successful response; costs 5 credits.","headers":{"X-Agent-Pass-Remaining":{"schema":{"type":"integer"}},"X-Credits-Remaining":{"schema":{"type":"integer"}},"X-Request-Id":{"schema":{"type":"string"}},"X-Schema-Version":{"schema":{"type":"string"}},"X-Usage-Cost":{"schema":{"type":"integer"}}}},"401":{"$ref":"#/components/responses/InvalidAgentPass"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/InvalidAgentPass"},"404":{"$ref":"#/components/responses/NotFound"},"410":{"$ref":"#/components/responses/InvalidAgentPass"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[],"summary":"Get Uma character data using an Agent Pass","tags":["Structured profiles"],"x-credit-cost":5}},"/api/v1/pricing":{"get":{"operationId":"getStructuredAccessPricing","responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":true,"type":"object"}}},"description":"Free pricing document."}},"security":[],"summary":"Read current credit prices","tags":["Discovery"],"x-credit-cost":0}},"/api/v1/umas/{slug}":{"get":{"operationId":"getBasicHorse","parameters":[{"description":"Stable UmaArchive horse slug.","example":"special-week","in":"path","name":"slug","required":true,"schema":{"pattern":"^[a-z0-9-]+$","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BasicHorse"}}},"description":"Successful response; costs 2 credits.","headers":{"X-Credits-Remaining":{"schema":{"type":"integer"}},"X-Request-Id":{"schema":{"type":"string"}},"X-Schema-Version":{"schema":{"type":"string"}},"X-Usage-Cost":{"schema":{"type":"integer"}}}},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[{},{"BearerAuth":[]},{"ApiKeyAuth":[]}],"summary":"Get a basic horse lookup","tags":["Structured profiles"],"x-credit-cost":2}},"/api/v1/umas/{slug}/complete":{"get":{"operationId":"getCompleteProfile","parameters":[{"description":"Stable UmaArchive horse slug.","example":"special-week","in":"path","name":"slug","required":true,"schema":{"pattern":"^[a-z0-9-]+$","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompleteProfile"}}},"description":"Successful response; costs 10 credits.","headers":{"X-Credits-Remaining":{"schema":{"type":"integer"}},"X-Request-Id":{"schema":{"type":"string"}},"X-Schema-Version":{"schema":{"type":"string"}},"X-Usage-Cost":{"schema":{"type":"integer"}}}},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[{},{"BearerAuth":[]},{"ApiKeyAuth":[]}],"summary":"Get the complete bundled profile","tags":["Structured profiles"],"x-credit-cost":10}},"/api/v1/umas/{slug}/irl":{"get":{"operationId":"getIrlDataset","parameters":[{"description":"Stable UmaArchive horse slug.","example":"special-week","in":"path","name":"slug","required":true,"schema":{"pattern":"^[a-z0-9-]+$","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatasetEnvelope"}}},"description":"Successful response; costs 5 credits.","headers":{"X-Credits-Remaining":{"schema":{"type":"integer"}},"X-Request-Id":{"schema":{"type":"string"}},"X-Schema-Version":{"schema":{"type":"string"}},"X-Usage-Cost":{"schema":{"type":"integer"}}}},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[{},{"BearerAuth":[]},{"ApiKeyAuth":[]}],"summary":"Get all stored real-horse information","tags":["Structured profiles"],"x-credit-cost":5}},"/api/v1/umas/{slug}/races":{"get":{"operationId":"getRaceDataset","parameters":[{"description":"Stable UmaArchive horse slug.","example":"special-week","in":"path","name":"slug","required":true,"schema":{"pattern":"^[a-z0-9-]+$","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatasetEnvelope"}}},"description":"Successful response; costs 5 credits.","headers":{"X-Credits-Remaining":{"schema":{"type":"integer"}},"X-Request-Id":{"schema":{"type":"string"}},"X-Schema-Version":{"schema":{"type":"string"}},"X-Usage-Cost":{"schema":{"type":"integer"}}}},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[{},{"BearerAuth":[]},{"ApiKeyAuth":[]}],"summary":"Get all stored race information","tags":["Structured profiles"],"x-credit-cost":5}},"/api/v1/umas/{slug}/uma":{"get":{"operationId":"getUmaDataset","parameters":[{"description":"Stable UmaArchive horse slug.","example":"special-week","in":"path","name":"slug","required":true,"schema":{"pattern":"^[a-z0-9-]+$","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatasetEnvelope"}}},"description":"Successful response; costs 5 credits.","headers":{"X-Credits-Remaining":{"schema":{"type":"integer"}},"X-Request-Id":{"schema":{"type":"string"}},"X-Schema-Version":{"schema":{"type":"string"}},"X-Usage-Cost":{"schema":{"type":"integer"}}}},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[{},{"BearerAuth":[]},{"ApiKeyAuth":[]}],"summary":"Get all stored Uma character information","tags":["Structured profiles"],"x-credit-cost":5}}},"servers":[{"description":"UmaArchive production","url":"https://umaarchive.com"}],"tags":[{"description":"Free metadata and pricing endpoints.","name":"Discovery"},{"description":"Prepaid capability URLs for agents that cannot send custom headers.","name":"Agent Passes"},{"description":"Credit-metered archive data; these calls never start AI research.","name":"Structured profiles"}]}