{ "openapi": "3.1.0", "info": { "title": "OpenRecords API (planned)", "version": "0.0.1-preview", "summary": "Early access / preview. Draft of the planned API; not yet available.", "description": "Early access / preview. This is a draft of the planned OpenRecords API, which is **not yet available**: there is no public endpoint and no keys are issued. The server URL below is a placeholder and does not respond. Paths, parameters and response shapes may change before launch. All examples are synthetic (owner and address masked). Coverage in the preview is Texas only. Join the waitlist at https://openrecords.io/#waitlist.", "x-status": "preview-not-available" }, "externalDocs": { "description": "Overview, Texas coverage and waitlist", "url": "https://openrecords.io/" }, "servers": [ { "url": "https://api.openrecords.io", "description": "Placeholder host for the planned API. Not live; it does not serve requests yet." } ], "security": [ { "previewKey": [] } ], "tags": [ { "name": "records", "description": "Planned / preview, not yet available." } ], "paths": { "/v0/records/{state}/{county}/{account_id}": { "get": { "tags": [ "records" ], "operationId": "getRecord", "summary": "Get one normalized record (planned / preview, not yet available)", "description": "Planned / preview, not yet available. Returns the latest weekly snapshot of one property record. Matches the illustrative curl example on https://openrecords.io/#api.", "x-status": "planned", "parameters": [ { "name": "state", "in": "path", "required": true, "description": "Two-letter state code, lowercase. Only Texas (tx) is in the preview.", "schema": { "type": "string", "enum": [ "tx" ] }, "example": "tx" }, { "name": "county", "in": "path", "required": true, "description": "County name, lowercase with hyphens (for example travis).", "schema": { "type": "string", "pattern": "^[a-z][a-z-]*$" }, "example": "travis" }, { "name": "account_id", "in": "path", "required": true, "description": "County appraisal account or property ID.", "schema": { "type": "string" }, "example": "DEMO-0001234" } ], "responses": { "200": { "description": "Record found (illustrative).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordResponse" }, "examples": { "synthetic": { "$ref": "#/components/examples/SyntheticRecordResponse" } } } } }, "401": { "description": "Missing or invalid preview key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No record for that county and account ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v0/records/{state}/{county}": { "get": { "tags": [ "records" ], "operationId": "listRecords", "summary": "List records in a county by tax status (planned / preview, not yet available)", "description": "Planned / preview, not yet available. For example, delinquent accounts in one county.", "x-status": "planned", "parameters": [ { "name": "state", "in": "path", "required": true, "description": "Two-letter state code, lowercase. Only Texas (tx) is in the preview.", "schema": { "type": "string", "enum": [ "tx" ] }, "example": "tx" }, { "name": "county", "in": "path", "required": true, "description": "County name, lowercase with hyphens (for example travis).", "schema": { "type": "string", "pattern": "^[a-z][a-z-]*$" }, "example": "travis" }, { "name": "tax_status", "in": "query", "required": false, "description": "Filter by tax status.", "schema": { "type": "string", "enum": [ "paid", "due", "delinquent", "deferred" ] } }, { "name": "as_of", "in": "query", "required": false, "description": "Weekly snapshot date. Defaults to the latest snapshot.", "schema": { "type": "string", "format": "date" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque pagination cursor from meta.next_cursor.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Page of records (illustrative).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordList" }, "examples": { "synthetic": { "$ref": "#/components/examples/SyntheticRecordList" } } } } }, "401": { "description": "Missing or invalid preview key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v0/records/{state}/{county}/{account_id}/history": { "get": { "tags": [ "records" ], "operationId": "getRecordHistory", "summary": "Get a record across weekly snapshots (planned / preview, not yet available)", "description": "Planned / preview, not yet available.", "x-status": "planned", "parameters": [ { "name": "state", "in": "path", "required": true, "description": "Two-letter state code, lowercase. Only Texas (tx) is in the preview.", "schema": { "type": "string", "enum": [ "tx" ] }, "example": "tx" }, { "name": "county", "in": "path", "required": true, "description": "County name, lowercase with hyphens (for example travis).", "schema": { "type": "string", "pattern": "^[a-z][a-z-]*$" }, "example": "travis" }, { "name": "account_id", "in": "path", "required": true, "description": "County appraisal account or property ID.", "schema": { "type": "string" }, "example": "DEMO-0001234" }, { "name": "since", "in": "query", "required": false, "description": "Earliest snapshot date to include.", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Snapshots, newest first (illustrative).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordList" }, "examples": { "synthetic": { "$ref": "#/components/examples/SyntheticRecordList" } } } } }, "401": { "description": "Missing or invalid preview key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No record for that county and account ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "previewKey": { "type": "http", "scheme": "bearer", "description": "Preview key sent as Authorization: Bearer . Keys are not issued yet." } }, "schemas": { "Source": { "type": "object", "required": [ "role", "agency", "file", "file_date" ], "properties": { "role": { "type": "string", "enum": [ "appraisal", "tax" ] }, "agency": { "type": "string" }, "file": { "type": "string" }, "file_date": { "type": "string", "format": "date" }, "retrieved": { "type": "string", "format": "date" } } }, "Record": { "type": "object", "description": "One normalized property record. Owner and address fields carry what the county publishes; examples here are synthetic and masked.", "required": [ "schema", "record_id", "as_of", "jurisdiction", "source", "parcel", "values", "tax" ], "properties": { "schema": { "type": "string", "const": "openrecords.record.v0" }, "synthetic": { "type": "boolean", "description": "True only for sample/demo records." }, "record_id": { "type": "string" }, "as_of": { "type": "string", "format": "date", "description": "Date of the weekly snapshot this record was read from." }, "jurisdiction": { "type": "object", "required": [ "state", "county", "fips" ], "properties": { "state": { "type": "string" }, "county": { "type": "string" }, "fips": { "type": "string", "pattern": "^[0-9]{5}$" } } }, "source": { "type": "array", "items": { "$ref": "#/components/schemas/Source" } }, "parcel": { "type": "object", "properties": { "account_id": { "type": "string" }, "geo_id": { "type": "string" }, "property_type": { "type": "string", "enum": [ "real", "personal", "mineral", "mobile_home" ] }, "state_use_code": { "type": "string" }, "state_use_label": { "type": "string" }, "legal_description": { "type": "string" } } }, "owner": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "individual", "business", "government", "trust", "unknown" ] }, "mailing_address": { "type": "string" } } }, "situs": { "type": "object", "properties": { "address": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "zip5": { "type": "string" } } }, "values": { "type": "object", "properties": { "tax_year": { "type": "integer" }, "currency": { "type": "string", "const": "USD" }, "land": { "type": "number" }, "improvement": { "type": "number" }, "market": { "type": "number" }, "appraised": { "type": "number" }, "capped_value_loss": { "type": "number" } } }, "exemptions": { "type": "array", "items": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "label": { "type": "string" } } } }, "tax": { "type": "object", "properties": { "tax_year": { "type": "integer" }, "levy_total": { "type": "number" }, "paid_total": { "type": "number" }, "amount_due": { "type": "number" }, "status": { "type": "string", "enum": [ "paid", "due", "delinquent", "deferred", "unknown" ] }, "delinquent": { "type": "boolean" }, "first_delinquent_year": { "type": [ "integer", "null" ] }, "lawsuit_cause_number": { "type": [ "string", "null" ] }, "deferral": { "type": "boolean" }, "taxing_units": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "levy": { "type": "number" }, "paid": { "type": "number" } } } } } }, "history": { "type": "object", "properties": { "cadence": { "type": "string", "const": "weekly" }, "snapshots": { "type": "array", "items": { "type": "string", "format": "date" } }, "changed_since_previous": { "type": [ "array", "null" ], "items": { "type": "string" } } } } } }, "RecordResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Record" }, "meta": { "type": "object", "properties": { "schema": { "type": "string" }, "synthetic": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } } } }, "RecordList": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Record" } }, "meta": { "type": "object", "properties": { "schema": { "type": "string" }, "synthetic": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } } } }, "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "examples": { "SyntheticRecordResponse": { "summary": "Synthetic record response (owner and address masked; not a real property)", "value": { "data": { "schema": "openrecords.record.v0", "synthetic": true, "record_id": "or_tx_48453_DEMO-0001234", "as_of": "2026-09-27", "jurisdiction": { "state": "TX", "county": "Travis", "fips": "48453" }, "source": [ { "role": "appraisal", "agency": "Travis Central Appraisal District", "file": "PROP.TXT (2026 appraisal export, supplement 334)", "file_date": "2026-09-03", "retrieved": "2026-09-27" }, { "role": "tax", "agency": "Travis County Tax Office", "file": "TaxCurOpenData.csv", "file_date": "2026-09-23", "retrieved": "2026-09-27" } ], "parcel": { "account_id": "DEMO-0001234", "geo_id": "DEMO-0000-0000-0000", "property_type": "real", "state_use_code": "A1", "state_use_label": "Single-family residence", "legal_description": "[masked]" }, "owner": { "name": "[masked]", "type": "individual", "mailing_address": "[masked]" }, "situs": { "address": "[masked]", "city": "Austin", "state": "TX", "zip5": "787xx" }, "values": { "tax_year": 2026, "currency": "USD", "land": 180000, "improvement": 320000, "market": 500000, "appraised": 500000, "capped_value_loss": 0 }, "exemptions": [ { "code": "HS", "label": "General residence homestead" } ], "tax": { "tax_year": 2025, "levy_total": 9150.0, "paid_total": 9150.0, "amount_due": 0.0, "status": "paid", "delinquent": false, "first_delinquent_year": null, "lawsuit_cause_number": null, "deferral": false, "taxing_units": [ { "code": "UNIT-A", "levy": 4300.0, "paid": 4300.0 }, { "code": "UNIT-B", "levy": 2950.0, "paid": 2950.0 }, { "code": "UNIT-C", "levy": 1900.0, "paid": 1900.0 } ] }, "history": { "cadence": "weekly", "snapshots": [ "2026-09-27" ], "changed_since_previous": null } }, "meta": { "schema": "openrecords.record.v0", "synthetic": true } } }, "SyntheticRecordList": { "summary": "Synthetic list response", "value": { "data": [ { "schema": "openrecords.record.v0", "synthetic": true, "record_id": "or_tx_48453_DEMO-0001234", "as_of": "2026-09-27", "jurisdiction": { "state": "TX", "county": "Travis", "fips": "48453" }, "source": [ { "role": "appraisal", "agency": "Travis Central Appraisal District", "file": "PROP.TXT (2026 appraisal export, supplement 334)", "file_date": "2026-09-03", "retrieved": "2026-09-27" }, { "role": "tax", "agency": "Travis County Tax Office", "file": "TaxCurOpenData.csv", "file_date": "2026-09-23", "retrieved": "2026-09-27" } ], "parcel": { "account_id": "DEMO-0001234", "geo_id": "DEMO-0000-0000-0000", "property_type": "real", "state_use_code": "A1", "state_use_label": "Single-family residence", "legal_description": "[masked]" }, "owner": { "name": "[masked]", "type": "individual", "mailing_address": "[masked]" }, "situs": { "address": "[masked]", "city": "Austin", "state": "TX", "zip5": "787xx" }, "values": { "tax_year": 2026, "currency": "USD", "land": 180000, "improvement": 320000, "market": 500000, "appraised": 500000, "capped_value_loss": 0 }, "exemptions": [ { "code": "HS", "label": "General residence homestead" } ], "tax": { "tax_year": 2025, "levy_total": 9150.0, "paid_total": 9150.0, "amount_due": 0.0, "status": "paid", "delinquent": false, "first_delinquent_year": null, "lawsuit_cause_number": null, "deferral": false, "taxing_units": [ { "code": "UNIT-A", "levy": 4300.0, "paid": 4300.0 }, { "code": "UNIT-B", "levy": 2950.0, "paid": 2950.0 }, { "code": "UNIT-C", "levy": 1900.0, "paid": 1900.0 } ] }, "history": { "cadence": "weekly", "snapshots": [ "2026-09-27" ], "changed_since_previous": null } } ], "meta": { "schema": "openrecords.record.v0", "synthetic": true, "next_cursor": null } } } } } }