{"openapi":"3.1.0","info":{"title":"ValiFit Public API","version":"1.0.0","description":"Versioned, JSON-LD-shaped public API for the ValiFit real-estate platform. Read the constitutional charters at https://valifit.com/trust/charters before building against this surface — the same compliance rules that govern the web product govern the API responses.","termsOfService":"https://valifit.com/terms","contact":{"name":"ValiFit API","email":"api@valifit.com","url":"https://valifit.com/trust"},"license":{"name":"ValiFit API Terms","url":"https://valifit.com/trust/data-license"}},"servers":[{"url":"https://valifit.com/api/v1","description":"Production"}],"tags":[{"name":"agents","description":"Public real-estate agent profiles + AQS"},{"name":"health","description":"API liveness + readiness"},{"name":"meta","description":"API metadata (this spec, knowledge graph)"}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"vfk_<plaintext-key>","description":"Bearer token in the Authorization header. Public-tier requests work without a key (60 req/min/IP). API keys lift the limit + enable write scopes."}},"schemas":{"Envelope":{"type":"object","required":["@context","api_version","request_id","served_at","status","cache","data"],"properties":{"@context":{"type":"string","format":"uri","example":"https://valifit.com/ld/v1"},"api_version":{"type":"string","example":"1"},"request_id":{"type":"string","format":"uuid"},"served_at":{"type":"string","format":"date-time"},"status":{"type":"string","enum":["ok","error"]},"cache":{"$ref":"#/components/schemas/CacheMeta"},"links":{"$ref":"#/components/schemas/Links"},"rate_limit":{"$ref":"#/components/schemas/RateLimit"},"data":{"description":"The endpoint-specific payload","nullable":true},"error":{"$ref":"#/components/schemas/ErrorDetail","nullable":true},"warnings":{"type":"array","items":{"type":"string"}}}},"CacheMeta":{"type":"object","required":["max_age"],"properties":{"max_age":{"type":"integer","example":300},"stale_if_error":{"type":"integer","example":3600}}},"Links":{"type":"object","required":["self"],"properties":{"self":{"type":"string"},"html":{"type":"string","description":"Human-facing equivalent URL"},"next":{"type":"string","description":"Canonical URL when slug differs"},"prev":{"type":"string"}}},"RateLimit":{"type":"object","required":["limit","remaining","reset_at"],"properties":{"limit":{"type":"integer","example":60},"remaining":{"type":"integer","example":58},"reset_at":{"type":"string","format":"date-time"}}},"ErrorDetail":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"agent_not_found"},"message":{"type":"string"}}},"Agent":{"type":"object","properties":{"@context":{"type":"string"},"@graph":{"type":"array"},"id":{"type":"integer"},"slug":{"type":"string"},"display_name":{"type":"string"},"professional_title":{"type":"string"},"brokerage":{"type":"string","nullable":true},"team_name":{"type":"string","nullable":true},"broker_name":{"type":"string","nullable":true},"photo_url":{"type":"string","nullable":true},"bio":{"type":"string","nullable":true},"specializations":{"type":"array","items":{"type":"string"}},"languages":{"type":"array","items":{"type":"string"}},"years_experience":{"type":"integer","nullable":true},"total_sales":{"type":"integer"},"service_municipalities":{"type":"array","items":{"type":"string"}},"service_counties":{"type":"array","items":{"type":"string"}},"license_number":{"type":"string","nullable":true},"license_state":{"type":"string","nullable":true},"accepting_leads":{"type":"boolean"},"member_since":{"type":"string","format":"date-time"},"last_active_at":{"type":"string","format":"date-time","nullable":true},"referral_code":{"type":"string","nullable":true,"pattern":"^VF-[A-Z0-9]{4}$"},"aqs":{"$ref":"#/components/schemas/AgentQualityScore","nullable":true}}},"AgentQualityScore":{"type":"object","properties":{"score":{"type":"number","minimum":0,"maximum":100},"response_rate":{"type":"number","nullable":true},"acceptance_rate":{"type":"number","nullable":true},"follow_through_rate":{"type":"number","nullable":true},"market_cohort":{"type":"string","nullable":true},"cohort_percentile":{"type":"number","nullable":true},"calculated_at":{"type":"string","format":"date-time"}}},"Health":{"type":"object","properties":{"status":{"type":"string","enum":["ok","degraded","down"]},"version":{"type":"string","example":"1"},"checks":{"type":"object","additionalProperties":true},"git_commit":{"type":"string","nullable":true},"git_branch":{"type":"string","nullable":true},"deployment_id":{"type":"string","nullable":true},"region":{"type":"string","nullable":true}}}},"responses":{"RateLimitExceeded":{"description":"Too many requests","content":{"application/ld+json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"NotFound":{"description":"Resource not found","content":{"application/ld+json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}}}},"security":[],"paths":{"/health":{"get":{"tags":["health"],"summary":"Liveness + readiness check","description":"Returns API status, DB ping, and deployment metadata.","responses":{"200":{"description":"Health snapshot","content":{"application/ld+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Health"}}}]}}}},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}}},"/agents/{slug}":{"get":{"tags":["agents"],"summary":"Get a public agent profile by slug","description":"Returns the JSON-LD-shaped agent profile (Schema.org RealEstateAgent) plus flat conveniences. Same data as the public /agents/{slug} page. Strict no-PII: never returns email, phone, address, or internal user_id.","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"example":"maria-castellano-26","description":"Agent slug. Format: <name>-<id> (preferred) or <id>. Non-canonical slugs return the resource with a warning + canonical URL in links.next."}],"responses":{"200":{"description":"Agent profile","content":{"application/ld+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Agent"}}}]}}}},"400":{"description":"Invalid slug","content":{"application/ld+json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}}},"/openapi.json":{"get":{"tags":["meta"],"summary":"This OpenAPI 3.1 spec","description":"Returns the v1 API specification document. Self-describing.","responses":{"200":{"description":"The spec","content":{"application/json":{}}}}}}}}