openapi: 3.1.0 info: title: Inheritage API Suite version: 1.0.0 description: | Public cultural heritage API by the Inheritage Foundation. - License: CC-BY-4.0 — visible attribution required - Contact: hello@inheritage.foundation - Terms: https://www.inheritage.foundation/terms-of-service contact: name: Inheritage Foundation url: https://www.inheritage.foundation email: hello@inheritage.foundation license: name: CC BY 4.0 url: https://creativecommons.org/licenses/by/4.0/ x-api-revision: 2025-02-02 servers: - url: https://www.inheritage.foundation/api/v1 description: Production tags: - name: Heritage description: Canonical heritage dataset - name: Geo description: Geospatial representations - name: Media description: Media bundles and assets - name: Citation description: Attribution utilities and compliance - name: AI description: AI context, embeddings, similarity, and vector federation - name: CIDOC-CRM description: CIDOC-CRM 7.1.3 JSON-LD (ISO 21127:2023) - name: LIDO description: LIDO 1.1 XML for museum data exchange - name: OAI-PMH description: OAI-PMH 2.0 harvesting protocol - name: AAT description: Art & Architecture Thesaurus (Inheritage + Getty AAT) - name: Governance description: Licensing, versioning, and operational governance - name: System description: Platform metadata and statistics paths: /: get: tags: [System] summary: API dataset manifest operationId: getDatasetManifest responses: "200": description: Dataset metadata content: application/json: schema: $ref: "#/components/schemas/DatasetManifest" default: $ref: "#/components/responses/ErrorResponse" /stats: get: tags: [System] summary: Heritage dataset statistics operationId: getDatasetStats responses: "200": description: Aggregated counts content: application/json: schema: $ref: "#/components/schemas/StatsResponse" default: $ref: "#/components/responses/ErrorResponse" /heritage: get: tags: [Heritage] summary: List heritage sites operationId: listHeritage parameters: - $ref: "#/components/parameters/StateParam" - $ref: "#/components/parameters/DynastyParam" - $ref: "#/components/parameters/StyleParam" - $ref: "#/components/parameters/MaterialParam" - $ref: "#/components/parameters/PeriodParam" - $ref: "#/components/parameters/CountryParam" - $ref: "#/components/parameters/LimitParam" - $ref: "#/components/parameters/OffsetParam" - $ref: "#/components/parameters/FieldsParam" - $ref: "#/components/parameters/SortParam" responses: "200": description: Paginated heritage response headers: Link: schema: type: string description: Pagination links (RFC 8288) content: application/json: schema: $ref: "#/components/schemas/HeritageList" default: $ref: "#/components/responses/ErrorResponse" /heritage/{slug}: get: tags: [Heritage] summary: Get heritage site detail operationId: getHeritage parameters: - name: slug in: path required: true schema: type: string description: Heritage slug - $ref: "#/components/parameters/FieldsParam" responses: "200": description: Heritage detail headers: ETag: schema: type: string Link: schema: type: string content: application/json: schema: $ref: "#/components/schemas/Heritage" "404": $ref: "#/components/responses/NotFound" default: $ref: "#/components/responses/ErrorResponse" /heritage/search: get: tags: [Heritage] summary: Search heritage sites operationId: searchHeritage parameters: - name: q in: query required: true schema: type: string description: Search query - $ref: "#/components/parameters/StateParam" - $ref: "#/components/parameters/StyleParam" - $ref: "#/components/parameters/CountryParam" - $ref: "#/components/parameters/LimitParam" - $ref: "#/components/parameters/FieldsParam" responses: "200": description: Heritage search results content: application/json: schema: type: object properties: data: type: array items: $ref: "#/components/schemas/Heritage" meta: type: object properties: total: type: integer limit: type: integer example: data: [] meta: total: 0 limit: 25 default: $ref: "#/components/responses/ErrorResponse" /heritage/random: get: tags: [Heritage] summary: Get a random heritage site operationId: getRandomHeritage responses: "200": description: Random heritage site content: application/json: schema: $ref: "#/components/schemas/Heritage" "404": $ref: "#/components/responses/NotFound" default: $ref: "#/components/responses/ErrorResponse" /geo/heritage: get: tags: [Geo] summary: List heritage sites as GeoJSON operationId: listGeoHeritage parameters: - $ref: "#/components/parameters/StateParam" - $ref: "#/components/parameters/CountryParam" - name: category in: query schema: type: string - name: featured in: query schema: type: boolean - name: limit in: query schema: type: integer minimum: 1 maximum: 500 - name: bbox in: query description: Bounding box filter `minLon,minLat,maxLon,maxLat` schema: type: string responses: "200": description: GeoJSON feature collection content: application/geo+json: schema: $ref: "#/components/schemas/GeoFeatureCollection" application/json: schema: $ref: "#/components/schemas/GeoFeatureCollection" default: $ref: "#/components/responses/ErrorResponse" /geo/heritage/{slug}: get: tags: [Geo] summary: Heritage site GeoJSON feature operationId: getGeoHeritage parameters: - name: slug in: path required: true schema: type: string responses: "200": description: Feature content: application/geo+json: schema: $ref: "#/components/schemas/GeoFeature" application/json: schema: $ref: "#/components/schemas/GeoFeature" "404": $ref: "#/components/responses/NotFound" default: $ref: "#/components/responses/ErrorResponse" /geo/nearby: get: tags: [Geo] summary: Nearby heritage sites operationId: getGeoNearby parameters: - name: lat in: query required: true schema: type: number - name: lon in: query required: true schema: type: number - name: radius_km in: query schema: type: number minimum: 1 maximum: 250 responses: "200": description: Nearby result set content: application/geo+json: schema: $ref: "#/components/schemas/GeoFeatureCollection" application/json: schema: $ref: "#/components/schemas/GeoFeatureCollection" default: $ref: "#/components/responses/ErrorResponse" /media/{slug}: get: tags: [Media] summary: Media bundle for heritage site operationId: getMedia parameters: - name: slug in: path required: true schema: type: string responses: "200": description: Media bundle content: application/json: schema: $ref: "#/components/schemas/MediaResponse" "404": $ref: "#/components/responses/NotFound" default: $ref: "#/components/responses/ErrorResponse" /media/search: get: tags: [Media] summary: Search media across heritage sites operationId: searchMedia parameters: - name: type in: query schema: type: string enum: [image, model, tour, diagram, video] - $ref: "#/components/parameters/StateParam" - $ref: "#/components/parameters/StyleParam" - $ref: "#/components/parameters/CountryParam" - $ref: "#/components/parameters/LimitParam" - $ref: "#/components/parameters/OffsetParam" responses: "200": description: Media search content: application/json: schema: $ref: "#/components/schemas/MediaSearchResponse" default: $ref: "#/components/responses/ErrorResponse" /media/random: get: tags: [Media] summary: Random heritage media bundle operationId: getRandomMedia responses: "200": description: Media bundle content: application/json: schema: $ref: "#/components/schemas/MediaResponse" "404": $ref: "#/components/responses/NotFound" default: $ref: "#/components/responses/ErrorResponse" /citation/{entityId}: get: tags: [Citation] summary: Canonical citation snippet operationId: getCitation parameters: - name: entityId in: path required: true schema: type: string responses: "200": description: Citation payload content: application/json: schema: $ref: "#/components/schemas/CitationResponse" "404": $ref: "#/components/responses/NotFound" default: $ref: "#/components/responses/ErrorResponse" /citation/report: post: tags: [Citation] summary: Record citation display operationId: postCitationReport requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CitationReportRequest" responses: "202": description: Accepted content: application/json: schema: type: object properties: status: type: string message: type: string example: status: accepted message: Citation display recorded default: $ref: "#/components/responses/ErrorResponse" /dump/heritage.ndjson: get: tags: [System] summary: Streaming NDJSON dump of all published heritage sites operationId: dumpHeritageNDJSON description: | Returns a live stream of all published heritage sites in NDJSON format (one JSON object per line). Includes dataset hash, last modified timestamp, and total count headers for freshness detection. parameters: - name: limit in: query schema: type: integer minimum: 100 maximum: 5000 default: 1000 - name: offset in: query schema: type: integer minimum: 0 default: 0 responses: "200": description: NDJSON stream headers: X-Dataset-Hash: schema: type: string description: SHA256 hash of dataset for freshness detection X-Total-Count: schema: type: integer description: Total number of records in dataset X-Published-Count: schema: type: integer description: Number of published records Last-Modified: schema: type: string format: date-time description: Last update timestamp ETag: schema: type: string description: Entity tag for caching Cache-Control: schema: type: string description: Cache directives content: application/x-ndjson: schema: type: string default: $ref: "#/components/responses/ErrorResponse" /dump/geo.geojson: get: tags: [System] summary: Streaming GeoJSON dump of all published heritage sites operationId: dumpGeoJSON description: | Returns a GeoJSON FeatureCollection of all published heritage sites with geospatial coordinates. Includes dataset hash and freshness headers. parameters: - name: limit in: query schema: type: integer minimum: 100 maximum: 5000 default: 1000 - name: offset in: query schema: type: integer minimum: 0 default: 0 responses: "200": description: GeoJSON FeatureCollection stream headers: X-Dataset-Hash: schema: type: string X-Total-Count: schema: type: integer X-Published-Count: schema: type: integer Last-Modified: schema: type: string format: date-time ETag: schema: type: string Cache-Control: schema: type: string content: application/geo+json: schema: $ref: "#/components/schemas/GeoFeatureCollection" default: $ref: "#/components/responses/ErrorResponse" /dump/ai-context.jsonl: get: tags: [System] summary: Streaming JSONL dump of AI context for all published heritage sites operationId: dumpAIContextJSONL description: | Returns AI context data in JSONL format (one JSON object per line). Each line contains slug, context, and optionally embedding vector. parameters: - name: limit in: query schema: type: integer minimum: 100 maximum: 5000 default: 1000 - name: offset in: query schema: type: integer minimum: 0 default: 0 - name: include in: query schema: type: string enum: [embedding, metadata] description: Include embedding vectors or metadata in output responses: "200": description: JSONL stream headers: X-Dataset-Hash: schema: type: string X-Total-Count: schema: type: integer X-Published-Count: schema: type: integer Last-Modified: schema: type: string format: date-time ETag: schema: type: string Cache-Control: schema: type: string content: application/jsonl: schema: type: string default: $ref: "#/components/responses/ErrorResponse" /changes: get: tags: [System] summary: Dataset changefeed for incremental updates operationId: getChangefeed description: | Returns all heritage site changes (creates, updates, deletes) since a given timestamp. Use for incremental syncing and snapshot triggers. parameters: - name: since in: query required: true schema: type: string format: date-time description: ISO8601 timestamp to fetch changes from - name: limit in: query schema: type: integer minimum: 1 maximum: 1000 default: 100 responses: "200": description: Changefeed response headers: X-Dataset-Hash: schema: type: string content: application/json: schema: type: object properties: changes: type: array items: type: object properties: slug: type: string operation: type: string enum: [created, updated, deleted] updated_at: type: string format: date-time created_at: type: string format: date-time published: type: boolean checksum: type: string meta: type: object properties: since: type: string format: date-time until: type: string format: date-time next_since: type: string format: date-time total_changes: type: integer dataset_hash: type: string last_updated: type: string format: date-time "400": $ref: "#/components/responses/BadRequest" default: $ref: "#/components/responses/ErrorResponse" /ai/context/{slug}: get: tags: [AI] summary: Heritage AI context bundle operationId: getAiContext parameters: - name: slug in: path required: true schema: type: string responses: "200": description: Context payload headers: X-Embedding-Model: schema: type: string X-Embedding-Model-Version: schema: type: string X-Prompt-Template-Version: schema: type: string X-Retrieval-Policy: schema: type: string X-Embedding-Checksum: schema: type: string AI-Use-Allowed: schema: type: string AI-License-Terms: schema: type: string content: application/json: schema: $ref: "#/components/schemas/AiContextResponse" "404": $ref: "#/components/responses/NotFound" default: $ref: "#/components/responses/ErrorResponse" /ai/embedding/{slug}: get: tags: [AI] summary: Heritage embedding vector operationId: getAiEmbedding parameters: - name: slug in: path required: true schema: type: string responses: "200": description: Embedding headers: X-Embedding-Model: schema: type: string X-Embedding-Model-Version: schema: type: string X-Prompt-Template-Version: schema: type: string X-Retrieval-Policy: schema: type: string X-Embedding-Checksum: schema: type: string AI-Use-Allowed: schema: type: string AI-License-Terms: schema: type: string content: application/json: schema: $ref: "#/components/schemas/AiEmbeddingResponse" "404": $ref: "#/components/responses/NotFound" default: $ref: "#/components/responses/ErrorResponse" /ai/meta/{slug}: get: tags: [AI] summary: Machine-readable heritage AI metadata operationId: getAiMetadata parameters: - name: slug in: path required: true schema: type: string responses: "200": description: Metadata bundle headers: X-Embedding-Model: schema: type: string X-Embedding-Model-Version: schema: type: string X-Prompt-Template-Version: schema: type: string X-Retrieval-Policy: schema: type: string X-Embedding-Checksum: schema: type: string AI-Use-Allowed: schema: type: string AI-License-Terms: schema: type: string content: application/json: schema: $ref: "#/components/schemas/AiMetaResponse" "404": $ref: "#/components/responses/NotFound" default: $ref: "#/components/responses/ErrorResponse" /ai/vision/context: post: tags: [AI] summary: Image-based heritage context inference operationId: postAiVisionContext requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/AiVisionRequest" responses: "200": description: Vision context response headers: X-Embedding-Model: schema: type: string X-Embedding-Model-Version: schema: type: string X-Prompt-Template-Version: schema: type: string X-Retrieval-Policy: schema: type: string X-Embedding-Checksum: schema: type: string AI-Use-Allowed: schema: type: string AI-License-Terms: schema: type: string content: application/json: schema: $ref: "#/components/schemas/AiVisionResponse" default: $ref: "#/components/responses/ErrorResponse" /ai/vector-index.ndjson: get: tags: [AI] summary: NDJSON vector feed for periodic syncing operationId: getAiVectorIndex parameters: - name: limit in: query schema: type: integer minimum: 1 maximum: 500 - name: offset in: query schema: type: integer minimum: 0 responses: "200": description: Vector records in NDJSON headers: X-Embedding-Model: schema: type: string X-Embedding-Model-Version: schema: type: string X-Prompt-Template-Version: schema: type: string X-Retrieval-Policy: schema: type: string X-Embedding-Checksum: schema: type: string AI-Use-Allowed: schema: type: string AI-License-Terms: schema: type: string content: application/x-ndjson: schema: type: string description: Each line is a JSON object from AiVectorRecord examples: sample: value: | {"slug":"taj-mahal","vector":[0.12,0.03],"embedding_checksum":"abc123"} text/plain: schema: type: string default: $ref: "#/components/responses/ErrorResponse" /cidoc/{slug}: get: tags: [CIDOC-CRM] summary: Get heritage site in CIDOC-CRM JSON-LD format description: Returns heritage site in CIDOC-CRM 7.1.3 compliant JSON-LD with Getty AAT and Wikidata links operationId: getHeritageCIDOC parameters: - name: slug in: path required: true schema: type: string example: hoysaleswara-temple responses: "200": description: CIDOC-CRM JSON-LD representation headers: Content-Type: schema: type: string example: application/ld+json Link: schema: type: string example: ; rel="profile" X-CIDOC-Version: schema: type: string example: 7.1.3 X-CIDOC-Profile: schema: type: string example: Inheritage + Linked Art X-Compliance: schema: type: string example: UNESCO, Getty AAT, Wikidata, Europeana content: application/ld+json: schema: type: object properties: "@context": oneOf: - type: string - type: array "@type": type: string example: E22_Human-Made_Object "@id": type: string P1_is_identified_by: type: array P2_has_type: type: object P53_has_former_or_current_location: type: object sameAs: type: array items: type: string "404": $ref: "#/components/responses/ErrorResponse" "429": $ref: "#/components/responses/ErrorResponse" head: tags: [CIDOC-CRM] summary: Check if CIDOC-CRM representation exists operationId: checkHeritageCIDOC parameters: - name: slug in: path required: true schema: type: string responses: "200": description: CIDOC representation exists headers: X-CIDOC-URI: schema: type: string "404": description: Not found /lido/{slug}: get: tags: [LIDO] summary: Get heritage site in LIDO 1.1 XML format description: Returns heritage site in LIDO 1.1 XML for museum data exchange and Europeana integration operationId: getHeritageLIDO parameters: - name: slug in: path required: true schema: type: string example: red-fort - name: download in: query required: false schema: type: boolean default: false responses: "200": description: LIDO XML representation headers: Content-Type: schema: type: string example: application/xml; charset=utf-8 Content-Disposition: schema: type: string X-LIDO-Version: schema: type: string example: 1.1 content: application/xml: schema: type: string format: xml "404": description: Heritage site not found /lido/export: get: tags: [LIDO] summary: Bulk export heritage sites as LIDO XML (ZIP archive) description: Export multiple sites in LIDO 1.1 XML format as ZIP archive for institutional data feeds operationId: exportHeritageLIDO parameters: - name: state in: query schema: type: string example: Karnataka - name: country in: query schema: type: string default: India - name: category in: query schema: type: string enum: [Temple, Fort, Palace, Tomb, Monument] - name: limit in: query schema: type: integer minimum: 1 maximum: 1000 default: 100 - name: offset in: query schema: type: integer minimum: 0 default: 0 responses: "200": description: ZIP archive containing LIDO XML files headers: Content-Type: schema: type: string example: application/zip X-Export-Count: schema: type: integer X-Export-Errors: schema: type: integer content: application/zip: schema: type: string format: binary "404": description: No heritage sites found matching criteria /oai-pmh: get: tags: [OAI-PMH] summary: OAI-PMH 2.0 harvesting protocol description: OAI-PMH 2.0 endpoint for automated data harvesting by Europeana and institutional aggregators operationId: oaipmhHandler parameters: - name: verb in: query required: true schema: type: string enum: [Identify, ListMetadataFormats, ListSets, ListIdentifiers, ListRecords, GetRecord] - name: metadataPrefix in: query schema: type: string enum: [oai_dc, lido] - name: identifier in: query schema: type: string example: oai:inheritage.foundation:heritage:taj-mahal - name: from in: query schema: type: string format: date-time - name: until in: query schema: type: string format: date-time - name: set in: query schema: type: string example: state:Karnataka - name: resumptionToken in: query schema: type: string responses: "200": description: OAI-PMH XML response headers: Content-Type: schema: type: string example: text/xml; charset=utf-8 X-OAI-PMH-Version: schema: type: string example: 2.0 content: text/xml: schema: type: string format: xml /aat: get: tags: [AAT] summary: Search and list AAT (Art & Architecture Thesaurus) terms description: | Search and browse architectural styles from the Inheritage AAT, which combines Inheritage-specific styles with Getty AAT mappings for comprehensive coverage. operationId: searchAAT parameters: - name: q in: query schema: type: string description: Full-text search query example: Dravidian - name: limit in: query schema: type: integer minimum: 1 maximum: 100 default: 25 description: Maximum number of results - name: offset in: query schema: type: integer minimum: 0 default: 0 description: Pagination offset - name: regions in: query schema: type: string description: Filter by regions (comma-separated) example: Karnataka,Tamil Nadu - name: timePeriods in: query schema: type: string description: Filter by time periods (comma-separated) example: Medieval Period,Chola Period - name: dynasties in: query schema: type: string description: Filter by dynasties (comma-separated) example: Chola,Hoysala responses: "200": description: List of matching AAT terms headers: X-Inheritage-AAT-Version: schema: type: string example: 1.0.0 X-Inheritage-AAT-Profile: schema: type: string example: Inheritage + Getty AAT X-Compliance: schema: type: string example: Getty AAT, CIDOC-CRM, Linked Art X-Total-Count: schema: type: integer content: application/json: schema: $ref: "#/components/schemas/AATStyleListResponse" default: $ref: "#/components/responses/ErrorResponse" /aat/{id}: get: tags: [AAT] summary: Get a single AAT term by ID, slug, or style_id description: | Retrieve a single AAT term by UUID, slug, or style_id (INHF-... format). Returns full term details including metadata, related sites, and external mappings. operationId: getAATTerm parameters: - name: id in: path required: true schema: type: string description: AAT term UUID, slug, or style_id (e.g., "nagara-architecture-style" or "INHF-123456789-13-11-25-NA") example: nagara-architecture-style responses: "200": description: AAT term details headers: X-Inheritage-AAT-Version: schema: type: string X-Inheritage-AAT-Profile: schema: type: string X-Inheritage-AAT-URI: schema: type: string Link: schema: type: string description: Canonical URI link content: application/json: schema: $ref: "#/components/schemas/AATTerm" "404": $ref: "#/components/responses/NotFound" default: $ref: "#/components/responses/ErrorResponse" head: tags: [AAT] summary: Check if AAT term exists operationId: checkAATTerm parameters: - name: id in: path required: true schema: type: string responses: "200": description: AAT term exists headers: X-Inheritage-AAT-URI: schema: type: string "404": description: Not found /aat/reconcile: get: tags: [AAT] summary: OpenRefine reconciliation service metadata description: | Returns service metadata for OpenRefine reconciliation. This endpoint provides the service manifest required for OpenRefine to connect to the AAT reconciliation service. operationId: getAATReconcileMetadata responses: "200": description: Reconciliation service metadata content: application/json: schema: $ref: "#/components/schemas/AATReconciliationService" default: $ref: "#/components/responses/ErrorResponse" post: tags: [AAT] summary: OpenRefine-compatible reconciliation queries description: | Process reconciliation queries from OpenRefine or other reconciliation clients. Accepts batch queries and returns matching AAT terms with confidence scores. operationId: postAATReconcile requestBody: content: application/json: schema: oneOf: - type: object description: Service metadata request (no queries) - $ref: "#/components/schemas/AATReconciliationQueries" responses: "200": description: Reconciliation results headers: X-Reconciliation-Service: schema: type: string example: Inheritage AAT X-Inheritage-AAT-Version: schema: type: string content: application/json: schema: oneOf: - $ref: "#/components/schemas/AATReconciliationService" - $ref: "#/components/schemas/AATReconciliationResults" default: $ref: "#/components/responses/ErrorResponse" /dump/aat.ndjson: get: tags: [AAT] summary: Bulk export of all AAT terms in NDJSON format description: | Returns a complete dump of all AAT terms in NDJSON format (one JSON object per line). Includes dataset hash and freshness headers for cache validation. operationId: dumpAATNDJSON parameters: - name: limit in: query schema: type: integer minimum: 1 maximum: 100000 default: 100000 description: Maximum number of terms to export responses: "200": description: NDJSON stream of AAT terms headers: X-Dataset-Hash: schema: type: string description: SHA256 hash of dataset for freshness detection X-Dataset-Count: schema: type: integer description: Total number of terms in dataset X-Dataset-Generated-At: schema: type: string format: date-time description: Timestamp when dump was generated Content-Disposition: schema: type: string example: attachment; filename="aat.ndjson" Cache-Control: schema: type: string example: public, max-age=3600, stale-while-revalidate=86400 content: application/x-ndjson: schema: type: string description: Each line is a JSON object representing an AAT term default: $ref: "#/components/responses/ErrorResponse" /license/ai: get: tags: [Governance] summary: AI license addendum metadata operationId: getAiLicense responses: "200": description: AI license metadata content: application/json: schema: $ref: "#/components/schemas/AiLicenseResponse" default: $ref: "#/components/responses/ErrorResponse" /ai/similar: post: tags: [AI] summary: Similar heritage sites operationId: postAiSimilar requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/AiSimilarRequest" responses: "200": description: Similarity ranking headers: X-Embedding-Model: schema: type: string X-Embedding-Model-Version: schema: type: string X-Prompt-Template-Version: schema: type: string X-Retrieval-Policy: schema: type: string X-Embedding-Checksum: schema: type: string AI-Use-Allowed: schema: type: string AI-License-Terms: schema: type: string content: application/json: schema: $ref: "#/components/schemas/AiSimilarResponse" default: $ref: "#/components/responses/ErrorResponse" /ai/similar/{slug}: get: tags: [AI] summary: Find similar sites (GET alternative for crawlers) description: | Crawler-friendly GET endpoint for finding similar heritage sites. Use POST /ai/similar for custom embeddings or advanced queries. operationId: getAiSimilar parameters: - name: slug in: path required: true schema: type: string description: Heritage site slug - name: limit in: query schema: type: integer minimum: 1 maximum: 50 default: 10 description: Maximum results - name: threshold in: query schema: type: number format: float minimum: 0 maximum: 1 default: 0.7 description: Similarity threshold (0-1) responses: "200": description: Similar sites found headers: Cache-Control: schema: type: string description: "public, max-age=3600" X-Trace-Id: schema: type: string content: application/json: schema: type: object properties: slug: type: string similar: type: array items: type: object properties: slug: type: string name: type: string similarity: type: number meta: type: object properties: count: type: integer limit: type: integer threshold: type: number "404": description: Site not found default: $ref: "#/components/responses/ErrorResponse" /timeline/featured: get: tags: [System] summary: Get featured timeline links description: | Returns curated timeline links organized by country and category. Each link points to a public timeline experience on inheritage.foundation. operationId: getTimelineFeatured responses: "200": description: Featured timeline links headers: Cache-Control: schema: type: string description: "public, max-age=3600" X-Trace-Id: schema: type: string content: application/json: schema: type: object properties: data: type: array items: type: object properties: country: type: string links: type: array items: type: object properties: name: type: string href: type: string example: data: - country: "India" links: - name: "Timeline of Temples in India" href: "/timeline/temples-in-india" - country: "United States" links: - name: "Timeline of Museums in United States" href: "/timeline/museums-in-united-states" default: $ref: "#/components/responses/ErrorResponse" /sparql: get: tags: [CIDOC-CRM] summary: SPARQL query endpoint (GET) description: | SPARQL 1.1 query endpoint for querying heritage data in CIDOC-CRM format. Supports SELECT, ASK, CONSTRUCT, and DESCRIBE queries. operationId: getSparql parameters: - name: query in: query required: true schema: type: string description: SPARQL query string (URL-encoded) - name: format in: query schema: type: string enum: [json, xml, csv, tsv] default: json description: Response format responses: "200": description: SPARQL query results content: application/json: schema: type: object properties: head: type: object properties: vars: type: array items: type: string results: type: object properties: bindings: type: array items: type: object application/sparql-results+json: schema: type: object application/sparql-results+xml: schema: type: string text/csv: schema: type: string text/tab-separated-values: schema: type: string "400": description: Invalid SPARQL query content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" default: $ref: "#/components/responses/ErrorResponse" post: tags: [CIDOC-CRM] summary: SPARQL query endpoint (POST) description: | SPARQL 1.1 query endpoint for querying heritage data in CIDOC-CRM format. Accepts queries via request body (application/sparql-query or form-encoded). operationId: postSparql parameters: - name: format in: query schema: type: string enum: [json, xml, csv, tsv] default: json description: Response format - $ref: "#/components/parameters/AttributionHeader" requestBody: required: true content: application/sparql-query: schema: type: string example: | PREFIX crm: SELECT ?site ?name WHERE { ?site crm:P1_is_identified_by ?app . ?app crm:P190_has_symbolic_content ?name . } LIMIT 10 application/x-www-form-urlencoded: schema: type: object properties: query: type: string required: - query responses: "200": description: SPARQL query results content: application/json: schema: type: object application/sparql-results+json: schema: type: object application/sparql-results+xml: schema: type: string text/csv: schema: type: string text/tab-separated-values: schema: type: string "400": description: Invalid SPARQL query content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" default: $ref: "#/components/responses/ErrorResponse" options: tags: [CIDOC-CRM] summary: SPARQL endpoint CORS preflight operationId: optionsSparql responses: "200": description: CORS preflight response components: parameters: StateParam: name: state in: query schema: type: string DynastyParam: name: dynasty in: query schema: type: string StyleParam: name: style in: query schema: type: string MaterialParam: name: material in: query schema: type: string PeriodParam: name: period in: query schema: type: string CountryParam: name: country in: query schema: type: string LimitParam: name: limit in: query schema: type: integer minimum: 1 maximum: 100 OffsetParam: name: offset in: query schema: type: integer minimum: 0 FieldsParam: name: fields in: query description: Comma-separated list of fields to include schema: type: string SortParam: name: sort in: query description: Sort instruction (e.g. `name` or `-period`) schema: type: string responses: NotFound: description: Resource not found content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: error: code: NOT_FOUND message: Heritage site not found hint: Verify the slug or see https://www.inheritage.foundation/docs/errors#NOT_FOUND doc: https://www.inheritage.foundation/docs/errors#NOT_FOUND ErrorResponse: description: Request failed content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" schemas: ErrorEnvelope: type: object properties: error: type: object required: [code, message] properties: code: type: string message: type: string hint: type: string nullable: true doc: type: string format: uri trace_id: type: string DatasetManifest: type: object properties: dataset: type: object properties: "@context": type: string "@type": type: string name: type: string description: type: string license: type: string creator: type: object properties: "@type": type: string name: type: string url: type: string format: uri distribution: type: array items: type: object properties: "@type": type: string encodingFormat: type: string contentUrl: type: string format: uri keywords: type: array items: type: string homepage: type: string format: uri version: type: string modified: type: string format: date-time sameAs: type: array items: type: string format: uri links: type: array items: type: object properties: rel: type: string href: type: string StatsResponse: type: object properties: counts: type: object properties: total: type: integer published: type: integer featured: type: integer total_views: type: integer avg_completion_score: type: number format: float dataset_hash: type: string description: SHA256 hash of dataset for freshness detection last_updated: type: string format: date-time description: Timestamp of last dataset change breakdown: type: object properties: by_state: type: object additionalProperties: type: integer by_style: type: object additionalProperties: type: integer by_dynasty: type: object additionalProperties: type: integer by_status: type: object additionalProperties: type: integer by_country: type: object additionalProperties: type: integer HeritageList: type: object properties: data: type: array items: $ref: "#/components/schemas/Heritage" meta: type: object properties: total: type: integer limit: type: integer offset: type: integer Heritage: type: object properties: id: type: string slug: type: string uuid: type: string name: type: string summary: type: string nullable: true description: type: string nullable: true category: type: string nullable: true location: type: string nullable: true state: type: string nullable: true country: type: string nullable: true dynasty: type: string nullable: true period: type: string nullable: true year_built: type: string nullable: true built_by: type: string nullable: true heritage_status: type: string nullable: true preservation_status: type: string nullable: true coordinates: type: array items: type: number geolocation: type: object nullable: true properties: lat: type: number lon: type: number materials: type: array items: type: string architecture: type: object properties: style: type: string nullable: true structural_system: type: string nullable: true construction_technique: type: string nullable: true conservation_efforts: type: string nullable: true sustainability_features: type: string nullable: true dimensions: type: object properties: height: type: number nullable: true width: type: number nullable: true length: type: number nullable: true area: type: number nullable: true volume: type: number nullable: true visitor_info: type: object properties: visiting_hours: type: string nullable: true entry_fee: type: string nullable: true website: type: string nullable: true best_visit_times: type: string nullable: true facilities: type: array items: type: string restrictions: type: string nullable: true accessibility: type: object nullable: true cultural_context: type: object properties: history: type: string nullable: true cultural_significance: type: string nullable: true cultural_continuity: type: string nullable: true traditional_knowledge: type: string nullable: true seasonal_events: type: array items: type: string tags: type: object properties: category: type: string nullable: true dynasty: type: string nullable: true period: type: string nullable: true states: type: array items: type: string media: type: object properties: primary_image: type: string nullable: true gallery: type: array items: type: string panoramas: type: array items: type: string orthos: type: array items: type: string floor_plans: type: array items: type: string sections: type: array items: type: string site_plan: type: string nullable: true point_cloud: type: string nullable: true mesh_data: type: string nullable: true cad_files: type: array items: type: string videos: type: array items: type: string documents: type: array items: type: string status: type: object properties: completion_score: type: number nullable: true completion_status: type: string nullable: true is_featured: type: boolean nullable: true is_published: type: boolean nullable: true view_count: type: integer nullable: true timeline: type: array items: type: object references: type: array items: $ref: "#/components/schemas/HeritageReference" analytics: type: object properties: virtual_tour: type: object properties: enabled: type: boolean thumbnail: type: string nullable: true chapters_count: type: integer nullable: true data_points_count: type: integer nullable: true completion_rate: type: number nullable: true avg_session_duration: type: number nullable: true total_sessions: type: integer nullable: true citations: type: array items: $ref: "#/components/schemas/Citation" official_url: type: string same_as: type: array items: type: string format: uri HeritageReference: type: object properties: title: type: string nullable: true url: type: string nullable: true publisher: type: string nullable: true author: type: string nullable: true year: type: string nullable: true citation_text: type: string nullable: true Citation: type: object properties: name: type: string url: type: string license: type: string required_display: type: string GeoFeatureCollection: type: object properties: type: type: string enum: [FeatureCollection] features: type: array items: $ref: "#/components/schemas/GeoFeature" GeoFeature: type: object properties: type: type: string enum: [Feature] geometry: type: object properties: type: type: string coordinates: type: array items: type: number properties: type: object properties: slug: type: string nullable: true name: type: string nullable: true state: type: string nullable: true country: type: string nullable: true category: type: string nullable: true view_count: type: integer nullable: true completion_score: type: number nullable: true citation: $ref: "#/components/schemas/Citation" MediaResponse: type: object properties: heritage_id: type: string items: type: array items: $ref: "#/components/schemas/MediaItem" citations: type: array items: $ref: "#/components/schemas/Citation" metadata: type: object nullable: true MediaItem: type: object properties: type: type: string enum: [image, model, tour, diagram, video] url: type: string caption: type: string nullable: true license: type: string nullable: true citation: type: string metadata: type: object nullable: true MediaSearchResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/MediaResponse" meta: type: object properties: total: type: integer limit: type: integer offset: type: integer CitationResponse: type: object properties: entity: type: string citation_html: type: string citation_markdown: type: string citation_text: type: string license: type: string source_url: type: string format: uri CitationReportRequest: type: object required: [entity, app_name, domain] properties: entity: type: string app_name: type: string domain: type: string api_key: type: string nullable: true display_count: type: integer nullable: true AiContextResponse: type: object required: - slug - context - embedding - embedding_dimensions - embedding_checksum - model - model_version - prompt_template_version - retrieval_policy - sources - citation properties: slug: type: string context: type: string embedding: type: array items: type: number embedding_dimensions: type: integer embedding_checksum: type: string description: SHA-256 checksum of the embedding vector model: type: string description: Embedding model identifier model_version: type: string description: Embedding model release version prompt_template_version: type: string retrieval_policy: type: string sources: type: array items: type: object properties: type: type: string slug: type: string confidence: type: number retrieval_method: type: string required: [type, slug] citation: type: string AiEmbeddingResponse: type: object required: - slug - dimensions - embedding - embedding_checksum - model - model_version - prompt_template_version - retrieval_policy properties: slug: type: string dimensions: type: integer embedding: type: array items: type: number embedding_checksum: type: string description: SHA-256 checksum of the embedding vector model: type: string model_version: type: string prompt_template_version: type: string retrieval_policy: type: string AiMetaResponse: type: object required: - slug - name - license - model - model_version - prompt_template_version - retrieval_policy - embedding_dimensions - embedding_checksum - context - citations - sources properties: slug: type: string name: type: string locale: type: string nullable: true license: type: object properties: name: type: string citation_required: type: boolean ai_use_allowed: type: boolean ai_license_terms: type: string model: type: string model_version: type: string prompt_template_version: type: string retrieval_policy: type: string embedding_dimensions: type: integer embedding_checksum: type: string embeddings_last_updated: type: string format: date-time nullable: true context: type: string citations: type: array items: $ref: "#/components/schemas/Citation" same_as: type: array items: type: string sources: type: array items: type: object properties: type: type: string slug: type: string confidence: type: number retrieval_method: type: string safety_annotations: type: array items: type: string AiVisionRequest: type: object properties: image_url: type: string format: uri image_base64: type: string hint: type: string limit: type: integer minimum: 1 maximum: 10 anyOf: - required: [image_url] - required: [image_base64] AiVisionResponse: type: object properties: matches: type: array items: type: object properties: score: type: number slug: type: string name: type: string state: type: string nullable: true country: type: string nullable: true architecture_style: type: string nullable: true site: $ref: "#/components/schemas/Heritage" caption: type: string nullable: true architecture_style_prediction: type: string nullable: true embedding_model: type: string embedding_model_version: type: string prompt_template_version: type: string retrieval_policy: type: string embedding_dimensions: type: integer embedding_checksum: type: string license: type: string sources: type: array items: type: object properties: type: type: string slug: type: string confidence: type: number retrieval_method: type: string safety_annotations: type: array items: type: string trace_id: type: string AiLicenseResponse: type: object properties: name: type: string version: type: string license: type: string human_summary: type: string url: type: string requirements: type: object properties: attribution_header: type: string license_header: type: string ai_headers: type: object additionalProperties: type: string citation_snippets_endpoint: type: string obligations: type: array items: type: string allowances: type: array items: type: string prohibitions: type: array items: type: string enforcement: type: object properties: violation_reporting: type: string revocation_policy: type: string contact: type: string citation_examples: type: array items: $ref: "#/components/schemas/Citation" trace_id: type: string AiSimilarRequest: type: object properties: slug: type: string embedding: type: array items: type: number limit: type: integer minimum: 1 maximum: 10 AiSimilarResponse: type: object properties: data: type: array items: type: object properties: score: type: number site: $ref: "#/components/schemas/Heritage" meta: type: object properties: reference: type: string nullable: true limit: type: integer embedding_model: type: string embedding_model_version: type: string prompt_template_version: type: string retrieval_policy: type: string embedding_checksum: type: string query_type: type: string vector_dimensions: type: integer AATStyleListResponse: type: object required: [total, data, pagination] properties: total: type: integer description: Total number of matching terms data: type: array items: $ref: "#/components/schemas/AATTerm" pagination: type: object required: [page, pageSize, total, totalPages] properties: page: type: integer pageSize: type: integer total: type: integer totalPages: type: integer AATTerm: type: object required: [id, style_id, slug, label, uri] properties: id: type: string format: uuid description: Unique identifier (UUID) style_id: type: string description: Inheritage style ID (format: INHF-...) example: INHF-123456789-13-11-25-NA slug: type: string description: URL-friendly identifier example: nagara-architecture-style label: type: string description: Primary label/name example: Nagara Architecture Style uri: type: string format: uri description: Canonical URI for the term example: https://www.inheritage.foundation/aat/style/nagara-architecture-style description: type: string nullable: true description: Detailed description synonyms: type: array items: type: string description: Alternative names/synonyms fragments: type: array items: type: string description: Searchable fragments/keywords language: type: string default: en description: Language code (ISO 639-1) created_at: type: string format: date-time nullable: true updated_at: type: string format: date-time nullable: true version: type: string default: "1.0.0" description: Term version same_as: type: array items: type: string format: uri description: External vocabulary mappings (Getty AAT, Wikidata, etc.) aat_code: type: string nullable: true description: Getty AAT code if mapped geo_scope: type: array items: type: string description: Geographic regions where term is used metadata: $ref: "#/components/schemas/AATStyleMetadata" siteCount: type: integer description: Total number of heritage sites using this style primarySiteCount: type: integer description: Number of sites where this is the primary style examples: type: array items: type: object properties: site_slug: type: string url: type: string format: uri caption: type: string isPrimary: type: boolean description: Example heritage sites using this style AATStyleMetadata: type: object properties: regions: type: array items: type: string description: Geographic regions timePeriods: type: array items: type: string description: Historical time periods dynasties: type: array items: type: string description: Associated dynasties sacredContexts: type: array items: type: string description: Sacred or religious contexts associatedDeities: type: array items: type: string description: Associated deities primaryMaterials: type: array items: type: string description: Primary construction materials architecturalFeatures: type: array items: type: string description: Key architectural features keywords: type: array items: type: string description: Search keywords recommendedSources: type: array items: type: object properties: title: type: string type: type: string nullable: true url: type: string format: uri nullable: true notes: type: string nullable: true description: Recommended bibliographic sources AATReconciliationService: type: object required: [versions, name, identifierSpace, schemaSpace] properties: versions: type: array items: type: string example: ["0.2"] name: type: string example: Inheritage AAT Reconciliation Service identifierSpace: type: string format: uri example: https://www.inheritage.foundation/aat/ schemaSpace: type: string format: uri example: https://www.inheritage.foundation/aat/schema defaultTypes: type: array items: type: object properties: id: type: string name: type: string example: - id: Style name: Architectural Style view: type: object properties: url: type: string format: uri example: url: https://www.inheritage.foundation/aat/styles/{{id}} preview: type: object properties: url: type: string format: uri width: type: integer height: type: integer example: url: https://www.inheritage.foundation/api/v1/aat/{{id}} width: 400 height: 300 suggest: type: object properties: entity: type: object properties: service_url: type: string format: uri service_path: type: string AATReconciliationQueries: type: object additionalProperties: type: object properties: query: type: string limit: type: integer minimum: 1 maximum: 10 default: 3 type: type: string default: Style AATReconciliationResults: type: object additionalProperties: type: object properties: result: type: array items: type: object properties: id: type: string name: type: string type: type: array items: type: object properties: id: type: string name: type: string score: type: number format: float minimum: 0 maximum: 1 match: type: boolean uri: type: string format: uri