{
  "openapi": "3.0.3",
  "info": {
    "title": "AntiqueLens API",
    "version": "1.0.0",
    "description": "Research reports for antiques and collectibles: photographs in, ranked museum records with the evidence for and against out. A resemblance is never an authentication, and no price is ever stated. Only POST /api/v1/reports is billed, once, after the report is delivered."
  },
  "servers": [
    {
      "url": "https://antiquelens.sensifai.com"
    }
  ],
  "paths": {
    "/api/v1/meta": {
      "get": {
        "summary": "Closed vocabularies",
        "security": [
          {
            "bearer": []
          },
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Meta"
                }
              }
            }
          },
          "default": {
            "description": "Problem details (RFC 7807)",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "description": "Categories, materials, photo angles, collections and the fixed resemblance note."
      }
    },
    "/api/v1/preview": {
      "post": {
        "summary": "Check one photograph (free)",
        "security": [
          {
            "bearer": []
          },
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Preview"
                }
              }
            }
          },
          "default": {
            "description": "Problem details (RFC 7807)",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "description": "Focus and light only, no AI, never billed.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PreviewRequest"
              }
            }
          }
        }
      }
    },
    "/api/v1/lookup": {
      "post": {
        "summary": "Search the museum collections (free)",
        "security": [
          {
            "bearer": []
          },
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Lookup"
                }
              }
            }
          },
          "default": {
            "description": "Problem details (RFC 7807)",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "description": "Search results are not matches to your object and say nothing about authenticity or value.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LookupRequest"
              }
            }
          }
        }
      }
    },
    "/api/v1/reports": {
      "post": {
        "summary": "Start a research report (billed once, after success)",
        "security": [
          {
            "bearer": []
          },
          {
            "apiKey": []
          }
        ],
        "responses": {
          "202": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Accepted"
                }
              }
            }
          },
          "default": {
            "description": "Problem details (RFC 7807)",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "402": {
            "description": "No funds: the problem body carries top_up_url"
          },
          "403": {
            "description": "No subscription: the problem body carries subscribe_url"
          }
        },
        "description": "Send 1 to 8 photographs of one object. A set with no readable photo, no object, or no reachable collection fails and bills nothing. Poll the job.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/StartRequest"
              }
            },
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "photos": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "binary"
                    }
                  },
                  "labels": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "title": {
                    "type": "string"
                  },
                  "category": {
                    "type": "string"
                  },
                  "materials": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "height_cm": {
                    "type": "number"
                  },
                  "width_cm": {
                    "type": "number"
                  },
                  "depth_cm": {
                    "type": "number"
                  },
                  "provenance": {
                    "type": "string"
                  },
                  "notes": {
                    "type": "string"
                  },
                  "language": {
                    "type": "string"
                  }
                }
              }
            }
          }
        }
      },
      "get": {
        "summary": "List your reports",
        "security": [
          {
            "bearer": []
          },
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/ReportSummary"
                  }
                }
              }
            }
          },
          "default": {
            "description": "Problem details (RFC 7807)",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          }
        ]
      }
    },
    "/api/v1/reports/{id}": {
      "get": {
        "summary": "One delivered report",
        "security": [
          {
            "bearer": []
          },
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReportView"
                }
              }
            }
          },
          "default": {
            "description": "Problem details (RFC 7807)",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "description": "object_features, inscription, candidates, date_range_hypotheses, evidence_urls, provenance_unknowns, valuation_status, flags, checks.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/api/v1/jobs/{id}": {
      "get": {
        "summary": "Job status",
        "security": [
          {
            "bearer": []
          },
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Job"
                }
              }
            }
          },
          "default": {
            "description": "Problem details (RFC 7807)",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/api/v1/history": {
      "get": {
        "summary": "Research insights",
        "security": [
          {
            "bearer": []
          },
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/History"
                }
              }
            }
          },
          "default": {
            "description": "Problem details (RFC 7807)",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/collection": {
      "get": {
        "summary": "List catalogue objects",
        "security": [
          {
            "bearer": []
          },
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Object"
                  }
                }
              }
            }
          },
          "default": {
            "description": "Problem details (RFC 7807)",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Add a catalogue object",
        "security": [
          {
            "bearer": []
          },
          {
            "apiKey": []
          }
        ],
        "responses": {
          "201": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Object"
                }
              }
            }
          },
          "default": {
            "description": "Problem details (RFC 7807)",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ObjectInput"
              }
            }
          }
        }
      }
    },
    "/api/v1/collection/{id}": {
      "delete": {
        "summary": "Remove a catalogue object",
        "security": [
          {
            "bearer": []
          },
          {
            "apiKey": []
          }
        ],
        "responses": {
          "204": {
            "description": "OK"
          },
          "default": {
            "description": "Problem details (RFC 7807)",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearer": {
        "type": "http",
        "scheme": "bearer"
      },
      "apiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    },
    "schemas": {
      "Problem": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "status": {
            "type": "integer"
          },
          "detail": {
            "type": "string"
          },
          "top_up_url": {
            "type": "string"
          },
          "subscribe_url": {
            "type": "string"
          }
        }
      },
      "Meta": {
        "type": "object",
        "properties": {
          "categories": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "label": {
                  "type": "string"
                }
              }
            }
          },
          "materials": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "photo_labels": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "label": {
                  "type": "string"
                },
                "advice": {
                  "type": "string"
                }
              }
            }
          },
          "statuses": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "languages": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "label": {
                  "type": "string"
                }
              }
            }
          },
          "sources": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "label": {
                  "type": "string"
                }
              }
            }
          },
          "max_photos": {
            "type": "integer"
          },
          "resemblance_note": {
            "type": "string"
          }
        }
      },
      "PreviewRequest": {
        "type": "object",
        "properties": {
          "photo": {
            "type": "string",
            "description": "base64 JPEG or PNG"
          }
        }
      },
      "Preview": {
        "type": "object",
        "properties": {
          "quality_score": {
            "type": "integer"
          },
          "usable": {
            "type": "boolean"
          },
          "notes": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "palette": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "thumbnail": {
            "type": "string"
          }
        }
      },
      "LookupRequest": {
        "type": "object",
        "properties": {
          "query": {
            "type": "string"
          },
          "category": {
            "type": "string"
          },
          "limit": {
            "type": "integer"
          }
        }
      },
      "Lookup": {
        "type": "object",
        "properties": {
          "query": {
            "type": "string"
          },
          "records": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Record"
            }
          },
          "sources": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SourceStatus"
            }
          },
          "note": {
            "type": "string"
          }
        }
      },
      "Record": {
        "type": "object",
        "properties": {
          "source": {
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "maker": {
            "type": "string"
          },
          "culture": {
            "type": "string"
          },
          "period": {
            "type": "string"
          },
          "date_text": {
            "type": "string"
          },
          "date_from": {
            "type": "integer"
          },
          "date_to": {
            "type": "integer"
          },
          "medium": {
            "type": "string"
          },
          "classification": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "inscription": {
            "type": "string"
          },
          "dimensions": {
            "type": "string"
          },
          "image_url": {
            "type": "string"
          },
          "thumb_url": {
            "type": "string"
          },
          "url": {
            "type": "string"
          },
          "rights": {
            "type": "string"
          },
          "credit": {
            "type": "string"
          }
        }
      },
      "SourceStatus": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "queries": {
            "type": "integer"
          },
          "returned": {
            "type": "integer"
          },
          "ok": {
            "type": "boolean"
          },
          "error": {
            "type": "string"
          }
        }
      },
      "StartRequest": {
        "type": "object",
        "properties": {
          "photos": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "label": {
                  "type": "string"
                },
                "data": {
                  "type": "string"
                }
              }
            }
          },
          "title": {
            "type": "string"
          },
          "category": {
            "type": "string"
          },
          "materials": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "height_cm": {
            "type": "number"
          },
          "width_cm": {
            "type": "number"
          },
          "depth_cm": {
            "type": "number"
          },
          "provenance": {
            "type": "string"
          },
          "notes": {
            "type": "string"
          },
          "language": {
            "type": "string"
          }
        }
      },
      "Accepted": {
        "type": "object",
        "properties": {
          "job_id": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "poll": {
            "type": "string"
          }
        }
      },
      "Job": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "report_id": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "error": {
            "type": "string"
          },
          "created_at": {
            "type": "string"
          }
        }
      },
      "ReportSummary": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "created_at": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "category": {
            "type": "string"
          },
          "top_score": {
            "type": "integer"
          },
          "top_strength": {
            "type": "string"
          },
          "candidates": {
            "type": "integer"
          },
          "flags": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "date_from": {
            "type": "integer"
          },
          "date_to": {
            "type": "integer"
          },
          "photos": {
            "type": "integer"
          },
          "has_thumbnail": {
            "type": "boolean"
          },
          "error": {
            "type": "string"
          },
          "units": {
            "type": "integer"
          }
        }
      },
      "ReportView": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "created_at": {
            "type": "string"
          },
          "units": {
            "type": "integer"
          },
          "source": {
            "type": "string"
          },
          "report": {
            "$ref": "#/components/schemas/Report"
          },
          "saved": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "title": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "Report": {
        "type": "object",
        "properties": {
          "version": {
            "type": "string"
          },
          "language": {
            "type": "string"
          },
          "object_features": {
            "type": "object",
            "properties": {
              "category": {
                "type": "string"
              },
              "label": {
                "type": "string"
              },
              "materials": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "shape": {
                "type": "string"
              },
              "motifs": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "technique": {
                "type": "string"
              },
              "colours": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "origin_hypotheses": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "condition_notes": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          },
          "inscription": {
            "type": "object",
            "properties": {
              "items": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "text": {
                      "type": "string"
                    },
                    "kind": {
                      "type": "string"
                    },
                    "location": {
                      "type": "string"
                    },
                    "legibility": {
                      "type": "string"
                    },
                    "photo": {
                      "type": "integer"
                    }
                  }
                }
              },
              "hints": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "match": {
                      "type": "string"
                    },
                    "label": {
                      "type": "string"
                    },
                    "from": {
                      "type": "integer"
                    },
                    "to": {
                      "type": "integer"
                    },
                    "note": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "candidates": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Candidate"
            }
          },
          "date_range_hypotheses": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "from_year": {
                  "type": "integer"
                },
                "to_year": {
                  "type": "integer"
                },
                "basis": {
                  "type": "string"
                },
                "supported_by": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "conflicts_with": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "strength": {
                  "type": "string"
                }
              }
            }
          },
          "evidence_urls": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "provenance_stated": {
            "type": "string"
          },
          "provenance_unknowns": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "valuation_status": {
            "type": "object",
            "properties": {
              "status": {
                "type": "string"
              },
              "reason": {
                "type": "string"
              },
              "comparables": {
                "type": "integer"
              },
              "needs": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          },
          "flags": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "label": {
                  "type": "string"
                },
                "why": {
                  "type": "string"
                },
                "action": {
                  "type": "string"
                }
              }
            }
          },
          "context": {
            "type": "string"
          },
          "context_by_ai": {
            "type": "boolean"
          },
          "resemblance_note": {
            "type": "string"
          },
          "next_steps": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "search_terms": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "sources": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SourceStatus"
            }
          },
          "photos": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "index": {
                  "type": "integer"
                },
                "label": {
                  "type": "string"
                },
                "quality_score": {
                  "type": "integer"
                },
                "notes": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              }
            }
          },
          "checks": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "ok": {
                  "type": "boolean"
                },
                "detail": {
                  "type": "string"
                }
              }
            }
          },
          "checks_passed": {
            "type": "boolean"
          },
          "notes": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "Candidate": {
        "type": "object",
        "properties": {
          "rank": {
            "type": "integer"
          },
          "record": {
            "$ref": "#/components/schemas/Record"
          },
          "score": {
            "type": "integer"
          },
          "strength": {
            "type": "string"
          },
          "matched": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Evidence"
            }
          },
          "differing": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Evidence"
            }
          },
          "comparison": {
            "type": "string"
          },
          "comparison_by_ai": {
            "type": "boolean"
          }
        }
      },
      "Evidence": {
        "type": "object",
        "properties": {
          "field": {
            "type": "string"
          },
          "ours": {
            "type": "string"
          },
          "theirs": {
            "type": "string"
          },
          "weight": {
            "type": "number"
          },
          "note": {
            "type": "string"
          }
        }
      },
      "History": {
        "type": "object",
        "properties": {
          "kept": {
            "type": "boolean"
          },
          "days": {
            "type": "integer"
          },
          "total": {
            "type": "integer"
          },
          "weekly": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "week": {
                  "type": "string"
                },
                "count": {
                  "type": "integer"
                },
                "top_score": {
                  "type": "number"
                }
              }
            }
          },
          "categories": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "count": {
                  "type": "integer"
                }
              }
            }
          },
          "centuries": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "count": {
                  "type": "integer"
                }
              }
            }
          },
          "flags": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "count": {
                  "type": "integer"
                }
              }
            }
          },
          "sources": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "count": {
                  "type": "integer"
                }
              }
            }
          }
        }
      },
      "Object": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "category": {
            "type": "string"
          },
          "materials": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "status": {
            "type": "string"
          },
          "notes": {
            "type": "string"
          },
          "provenance": {
            "type": "string"
          },
          "report_id": {
            "type": "string"
          },
          "dates": {
            "type": "string"
          },
          "records": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "source": {
                  "type": "string"
                },
                "id": {
                  "type": "string"
                },
                "title": {
                  "type": "string"
                },
                "url": {
                  "type": "string"
                },
                "thumb_url": {
                  "type": "string"
                },
                "strength": {
                  "type": "string"
                },
                "score": {
                  "type": "integer"
                },
                "credit": {
                  "type": "string"
                }
              }
            }
          },
          "has_thumbnail": {
            "type": "boolean"
          },
          "created_at": {
            "type": "string"
          },
          "updated_at": {
            "type": "string"
          }
        }
      },
      "ObjectInput": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string"
          },
          "category": {
            "type": "string"
          },
          "materials": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "status": {
            "type": "string"
          },
          "notes": {
            "type": "string"
          },
          "provenance": {
            "type": "string"
          },
          "dates": {
            "type": "string"
          }
        }
      }
    }
  }
}