{ "openapi": "3.1.1", "info": { "title": "Ruumiradar API", "version": "1.0.0", "description": "Read-only V1, locally usable. External access is by prior agreement only. Public data endpoints and partner credentials are not activated. Website login grants no API access. No user accounts or image files. DeveloperFeed is a local dry-run contract, not a POST endpoint." }, "servers": [ { "url": "https://ruumiradar.ee/api/v1" } ], "paths": { "/meta": { "get": { "operationId": "get_meta", "tags": [ "Metadata" ], "summary": "Dataset version and current coverage", "parameters": [], "responses": { "200": { "description": "Source-linked response. IDs survive renaming.", "headers": { "ETag": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data" ] } } } }, "304": { "description": "ETag unchanged; empty body." }, "400": { "description": "Request rejected. See error.code and error.message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected. See error.code and error.message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Request rejected. See error.code and error.message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected. See error.code and error.message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects": { "get": { "operationId": "get_projects", "tags": [ "Projects" ], "summary": "List and filter projects", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 25 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 100000, "default": 0 } }, { "name": "company_id", "in": "query", "schema": { "type": "string" } }, { "name": "stage", "in": "query", "schema": { "type": "string", "enum": [ "planning", "adopted", "design", "building", "completed" ] } }, { "name": "municipality", "in": "query", "schema": { "type": "string" } }, { "name": "district", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Source-linked response. IDs survive renaming.", "headers": { "ETag": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectSummary" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "pagination", "meta" ] } } } }, "304": { "description": "ETag unchanged; empty body." }, "400": { "description": "Request rejected. See error.code and error.message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected. See error.code and error.message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Request rejected. See error.code and error.message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected. See error.code and error.message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{id}": { "get": { "operationId": "get_projects_id", "tags": [ "Projects" ], "summary": "Project, claims and original sources", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Source-linked response. IDs survive renaming.", "headers": { "ETag": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Project" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] } } } }, "304": { "description": "ETag unchanged; empty body." }, "400": { "description": "Request rejected. See error.code and error.message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected. See error.code and error.message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Request rejected. See error.code and error.message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected. See error.code and error.message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/companies": { "get": { "operationId": "get_companies", "tags": [ "Companies" ], "summary": "List companies (Organization only)", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 25 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 100000, "default": 0 } } ], "responses": { "200": { "description": "Source-linked response. IDs survive renaming.", "headers": { "ETag": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Company" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "pagination", "meta" ] } } } }, "304": { "description": "ETag unchanged; empty body." }, "400": { "description": "Request rejected. See error.code and error.message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected. See error.code and error.message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Request rejected. See error.code and error.message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected. See error.code and error.message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/companies/{id}": { "get": { "operationId": "get_companies_id", "tags": [ "Companies" ], "summary": "Company and linked project IDs", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Source-linked response. IDs survive renaming.", "headers": { "ETag": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Company" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] } } } }, "304": { "description": "ETag unchanged; empty body." }, "400": { "description": "Request rejected. See error.code and error.message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected. See error.code and error.message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Request rejected. See error.code and error.message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected. See error.code and error.message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/events": { "get": { "operationId": "get_events", "tags": [ "Events" ], "summary": "Source events; not an automatic change feed", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 25 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 100000, "default": 0 } }, { "name": "project_id", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Source-linked response. IDs survive renaming.", "headers": { "ETag": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "pagination", "meta" ] } } } }, "304": { "description": "ETag unchanged; empty body." }, "400": { "description": "Request rejected. See error.code and error.message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected. See error.code and error.message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Request rejected. See error.code and error.message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected. See error.code and error.message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "x-access-policy": { "external_access": "by_prior_agreement_only", "external_data_api_active": false, "self_service_registration": false, "website_login_grants_api_access": false, "partner_credentials_implemented": false, "activation_requires": [ "owner_approval", "revocable_partner_credentials", "partner_scopes", "enforced_usage_and_cost_limits" ] }, "components": { "schemas": { "Meta": { "type": "object", "properties": { "api_version": { "const": "1.0.0" }, "dataset_version": { "type": "string" }, "checked_on": { "type": "string", "format": "date" }, "automatic_monitoring": { "const": false }, "content_language": { "const": "et" }, "project_count": { "type": "integer" }, "company_count": { "type": "integer" }, "event_count": { "type": "integer" }, "license_note": { "type": "string" } }, "required": [ "api_version", "dataset_version", "checked_on", "automatic_monitoring" ] }, "Pagination": { "type": "object", "properties": { "total": { "type": "integer" }, "limit": { "type": "integer", "maximum": 50 }, "offset": { "type": "integer" }, "next_offset": { "type": [ "integer", "null" ] } }, "required": [ "total", "limit", "offset", "next_offset" ] }, "Error": { "type": "object", "properties": { "api_version": { "const": "1.0.0" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "api_version", "error" ] }, "Source": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" }, "type": { "type": "string" }, "published_on": { "type": [ "string", "null" ] }, "checked_on": { "type": [ "string", "null" ] }, "note": { "type": [ "string", "null" ] } }, "required": [ "id", "title", "url" ] }, "Participant": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string" }, "source_id": { "type": "string" }, "scope": { "type": "string" } }, "required": [ "id", "name", "role", "source_id", "scope" ] }, "ProjectSummary": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "official_website": { "type": [ "string", "null" ] }, "address": { "type": "string" }, "municipality": { "type": "string" }, "district": { "type": "string" }, "stage": { "type": "string", "enum": [ "planning", "adopted", "design", "building", "completed" ] }, "stage_label": { "type": "string" }, "scope": { "type": "string" }, "homes": { "type": [ "integer", "null" ] }, "checked_on": { "type": "string", "format": "date" }, "source_ids": { "type": "array", "items": { "type": "string" } }, "participants": { "type": "array", "items": { "$ref": "#/components/schemas/Participant" } }, "location": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "coordinates": { "type": "array", "items": { "type": "number" } }, "crs": { "const": "EPSG:4326" }, "source_url": { "type": "string" }, "precision": { "type": [ "string", "null" ] }, "checked_on": { "type": [ "string", "null" ] } }, "required": [ "coordinates", "crs", "source_url" ] } ] } }, "required": [ "id", "name", "url", "source_ids", "scope", "stage", "checked_on" ] }, "Claim": { "type": "object", "properties": { "field": { "type": "string" }, "value": {}, "scope": { "type": "string" }, "source_id": { "type": "string" }, "valid_at": { "type": [ "string", "null" ] }, "locator": { "type": "string" } }, "required": [ "field", "value", "scope", "source_id" ] }, "Project": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "official_website": { "type": [ "string", "null" ] }, "address": { "type": "string" }, "municipality": { "type": "string" }, "district": { "type": "string" }, "stage": { "type": "string", "enum": [ "planning", "adopted", "design", "building", "completed" ] }, "stage_label": { "type": "string" }, "scope": { "type": "string" }, "homes": { "type": [ "integer", "null" ] }, "checked_on": { "type": "string", "format": "date" }, "source_ids": { "type": "array", "items": { "type": "string" } }, "participants": { "type": "array", "items": { "$ref": "#/components/schemas/Participant" } }, "location": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "coordinates": { "type": "array", "items": { "type": "number" } }, "crs": { "const": "EPSG:4326" }, "source_url": { "type": "string" }, "precision": { "type": [ "string", "null" ] }, "checked_on": { "type": [ "string", "null" ] } }, "required": [ "coordinates", "crs", "source_url" ] } ] }, "description": { "type": "string" }, "description_source_id": { "type": [ "string", "null" ] }, "claims": { "type": "array", "items": { "$ref": "#/components/schemas/Claim" } }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/Source" } }, "timeline": { "type": "array", "items": { "type": "object", "description": "Source-linked history. when may be a year/month/day; source_check is not a construction event." } } }, "required": [ "id", "name", "url", "source_ids", "sources", "claims", "scope" ] }, "Company": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "const": "Organization" }, "url": { "type": "string" }, "project_ids": { "type": "array", "items": { "type": "string" } }, "roles": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "name", "type", "url", "project_ids", "roles" ] }, "Event": { "type": "object", "properties": { "id": { "type": "string" }, "project_id": { "type": "string" }, "date": { "type": "string", "format": "date" }, "title": { "type": "string" }, "text": { "type": "string" }, "source_id": { "type": "string" }, "url": { "type": "string" } }, "required": [ "id", "project_id", "date", "source_id", "url" ] }, "DeveloperFeed": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "Ruumiradar developer feed V1", "type": "object", "additionalProperties": false, "required": [ "schema_version", "company_id", "generated_at", "projects" ], "properties": { "schema_version": { "const": "1.0" }, "company_id": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "generated_at": { "type": "string", "format": "date-time" }, "projects": { "type": "array", "maxItems": 100, "items": { "type": "object", "additionalProperties": false, "required": [ "external_id", "name", "website", "source_updated_at" ], "properties": { "external_id": { "type": "string", "minLength": 1, "maxLength": 100 }, "ruumiradar_id": { "type": "string", "pattern": "^P[1-9][0-9]*$" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "website": { "type": "string", "format": "uri", "pattern": "^https://" }, "source_updated_at": { "type": "string", "format": "date-time" }, "stage": { "type": "string", "enum": [ "planning", "adopted", "design", "building", "completed" ] }, "homes": { "type": [ "integer", "null" ], "minimum": 0 }, "address": { "type": "string", "maxLength": 300 }, "open_house": { "type": "object", "additionalProperties": false, "required": [ "starts_at", "ends_at", "url" ], "properties": { "starts_at": { "type": "string", "format": "date-time" }, "ends_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri", "pattern": "^https://" } } } } } } } } } } }