{"openapi":"3.1.0","info":{"title":"Ochre Editions API","version":"1.0.0","summary":"Public-domain artworks from the world's museums, their prints and limited drops.","description":"Read-only catalogue data needs no key. Your own orders need a personal API key from your account (Agents and API keys), sent as a Bearer token. To buy, use the MCP server, which handles consent and spending limits.","termsOfService":"https://www.ochreeditions.com/legal/agents","contact":{"name":"Ochre Editions","url":"https://www.ochreeditions.com/developers"}},"servers":[{"url":"https://www.ochreeditions.com"}],"externalDocs":{"description":"Developer guide","url":"https://www.ochreeditions.com/developers"},"paths":{"/api/artworks":{"get":{"operationId":"listArtworks","summary":"Search and list artworks","parameters":[{"name":"q","in":"query","schema":{"type":"string","maxLength":120}},{"name":"museum","in":"query","schema":{"type":"string"}},{"name":"artist","in":"query","schema":{"type":"string"}},{"name":"colour","in":"query","schema":{"type":"string"}},{"name":"century","in":"query","schema":{"type":"integer"}},{"name":"movement","in":"query","schema":{"type":"string"}},{"name":"collection","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":24}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"The `next_cursor` from the previous page."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ArtworkCard"}},"next_cursor":{"type":["string","null"]},"total":{"type":"integer"}}}}}},"429":{"description":"Problem","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/artworks/{slug}":{"get":{"operationId":"getArtwork","summary":"One artwork with its record, prints and prices","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9-]+$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Artwork"}}}},"404":{"description":"Problem","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/collections":{"get":{"operationId":"listCollections","summary":"Editorial collections","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Collection"}},"next_cursor":{"type":["string","null"]},"total":{"type":"integer"}}}}}}}}},"/api/collections/{slug}":{"get":{"operationId":"getCollection","summary":"A collection and its works","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9-]+$"}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"The `next_cursor` from the previous page."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Collection"},{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ArtworkCard"}},"next_cursor":{"type":["string","null"]},"total":{"type":"integer"}}}]}}}},"404":{"description":"Problem","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/drops":{"get":{"operationId":"listDrops","summary":"Limited drops, past and coming","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Drop"}},"next_cursor":{"type":["string","null"]},"total":{"type":"integer"}}}}}}}}},"/api/drops/{slug}":{"get":{"operationId":"getDrop","summary":"A drop's live state","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9-]+$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Drop"}}}},"404":{"description":"Problem","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/galleries":{"get":{"operationId":"getGalleryPlan","summary":"The galleries' floor plan: floors, wings and rooms, and the default walk","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GalleryPlan"}}}},"429":{"description":"Problem","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/galleries/{room}":{"get":{"operationId":"getGalleryRoom","summary":"A curated room, hung for a hang","parameters":[{"name":"room","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9-]+$"}},{"name":"hang","in":"query","schema":{"type":"integer","minimum":0,"maximum":9999},"description":"The seeded order to hang the room in; today's when omitted."},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"The `next_cursor` from the previous page; bound to its gallery, hang and pinned work."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":16}},{"name":"include","in":"query","schema":{"type":"string","pattern":"^[a-z0-9-]+$"},"description":"An artwork slug in the room, pinned first."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Gallery"}}}},"400":{"description":"Problem","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Problem","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Problem","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/galleries/artist/{artist}":{"get":{"operationId":"getArtistGallery","summary":"An artist's gallery: `<artist-slug>`, `contemporaries-of-<slug>`, `unrecorded` or `unrecorded-<place>`","parameters":[{"name":"artist","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9-]+$"}},{"name":"hang","in":"query","schema":{"type":"integer","minimum":0,"maximum":9999},"description":"The seeded order to hang the room in; today's when omitted."},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"The `next_cursor` from the previous page; bound to its gallery, hang and pinned work."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":16}},{"name":"include","in":"query","schema":{"type":"string","pattern":"^[a-z0-9-]+$"},"description":"An artwork slug in the room, pinned first."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Gallery"}}}},"400":{"description":"Problem","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Problem","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Problem","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/galleries/style/{style}":{"get":{"operationId":"getStyleGallery","summary":"A style gallery: a movement, a period style, `<type>-<century>`, `<type>` or `colour-<name>`","parameters":[{"name":"style","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9-]+$"}},{"name":"hang","in":"query","schema":{"type":"integer","minimum":0,"maximum":9999},"description":"The seeded order to hang the room in; today's when omitted."},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"The `next_cursor` from the previous page; bound to its gallery, hang and pinned work."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":16}},{"name":"include","in":"query","schema":{"type":"string","pattern":"^[a-z0-9-]+$"},"description":"An artwork slug in the room, pinned first."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Gallery"}}}},"400":{"description":"Problem","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Problem","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Problem","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/galleries/era/{era}":{"get":{"operationId":"getEraGallery","summary":"A time-and-place gallery: `<century>-<place>`, `<century>`, `<place>` or `museum-<museum-slug>`","parameters":[{"name":"era","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9-]+$"}},{"name":"hang","in":"query","schema":{"type":"integer","minimum":0,"maximum":9999},"description":"The seeded order to hang the room in; today's when omitted."},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"The `next_cursor` from the previous page; bound to its gallery, hang and pinned work."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":16}},{"name":"include","in":"query","schema":{"type":"string","pattern":"^[a-z0-9-]+$"},"description":"An artwork slug in the room, pinned first."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Gallery"}}}},"400":{"description":"Problem","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Problem","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Problem","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/storefront":{"get":{"operationId":"getStorefront","summary":"The shop's configuration: currency, sizes, shipping, promotions","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/me/orders":{"get":{"operationId":"listMyOrders","summary":"Your orders","security":[{"personalKey":[]}],"parameters":[{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"example":"Bearer ochre_pk_DWY1avmt3Kl2T-CKWSBfWGJj9qcHKEVt"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/OrderSummary"}},"next_cursor":{"type":["string","null"]},"total":{"type":"integer"}}}}}},"401":{"description":"Problem","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Problem","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/me/orders/{number}":{"get":{"operationId":"getMyOrder","summary":"One of your orders","security":[{"personalKey":[]}],"parameters":[{"name":"number","in":"path","required":true,"schema":{"type":"string","pattern":"^OE-[A-Z0-9]{6}$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Problem","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Problem","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}}},"components":{"securitySchemes":{"personalKey":{"type":"http","scheme":"bearer","description":"A personal API key (`ochre_pk_…`) from your account, with the read scope."}},"schemas":{"ArtworkCard":{"type":"object","required":["id","slug","title","museum","url","image"],"properties":{"id":{"type":"integer"},"slug":{"type":"string"},"title":{"type":"string"},"artist":{"type":["string","null"]},"date":{"type":["string","null"]},"museum":{"type":"string"},"url":{"type":"string","format":"uri"},"image":{"type":"string","format":"uri"},"thumbnail":{"type":"string","format":"uri"}}},"Artwork":{"type":"object","properties":{"slug":{"type":"string"},"title":{"type":"string"},"credit":{"type":"string"},"licence":{"enum":["CC0-1.0","public-domain"]},"download_url":{"type":"string","format":"uri"},"prints":{"type":"array","items":{"type":"object","properties":{"format":{"type":"string"},"size":{"type":"string"},"price_cents":{"type":"integer"}}}},"links":{"type":"object","additionalProperties":{"type":"string","format":"uri"}}}},"Collection":{"type":"object","properties":{"slug":{"type":"string"},"title":{"type":"string"},"intro":{"type":"string"},"works":{"type":"integer"}}},"Drop":{"type":"object","properties":{"slug":{"type":"string"},"title":{"type":"string"},"status":{"enum":["upcoming","open","sold_out","ended"]},"opens_at":{"type":"string","format":"date-time"},"edition_size":{"type":"integer"},"sold":{"type":"integer"},"price_cents":{"type":"integer"}}},"OrderSummary":{"type":"object","properties":{"number":{"type":"string"},"status":{"type":"string"},"placed_at":{"type":"string","format":"date-time"},"total_cents":{"type":"integer"}}},"GalleryPlan":{"type":"object","properties":{"floors":{"type":"array","items":{"type":"object"}},"walk_order":{"type":"array","items":{"type":"string"}}}},"Gallery":{"type":"object","required":["key","type","title","hang","works","walls"],"properties":{"key":{"type":"string"},"type":{"enum":["room","artist","style","era"]},"title":{"type":"string"},"intro":{"type":"string"},"layout":{"enum":["long","enfilade","cabinet","rotunda","corridor","stair"]},"wing":{"type":"string"},"hang":{"type":"integer"},"url":{"type":"string","format":"uri"},"total":{"type":"integer"},"works":{"type":"array","items":{"type":"object"}},"walls":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"work_ids":{"type":"array","items":{"type":"integer"}}}}},"doors":{"type":"array","items":{"type":"object"}},"next_cursor":{"type":["string","null"]},"next":{"type":["object","null"]}}},"Problem":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}}}}}}