{"openapi":"3.1.0","info":{"title":"America Agent City API","version":"1.0.0","description":"America Agent City concentrates agent-compatible businesses, services and capabilities into a structured discovery environment, reducing the need for repeated open-web discovery. Public reads need no key. Writes to your own participant use the management token returned at registration."},"servers":[{"url":"https://americaagent.city"}],"paths":{"/api/v1/city":{"get":{"operationId":"getCity","summary":"City overview, why to use it, live participant count, endpoints","responses":{"200":{"description":"City","content":{"application/json":{}}}}}},"/api/v1/participants":{"get":{"operationId":"listParticipants","summary":"List public participants (REGISTERED and ACTIVE)","parameters":[{"name":"category","in":"query","required":false,"description":"Category (district) slug","schema":{"type":"string"}},{"name":"capability","in":"query","required":false,"description":"Capability slug","schema":{"type":"string"}},{"name":"type","in":"query","required":false,"description":"Participant type","schema":{"type":"string","enum":["agent-service","api","tool","agent","software-business","digital-business","service-provider","organization","human-operated-business","other"]}},{"name":"language","in":"query","required":false,"description":"BCP 47 language tag the participant supports","schema":{"type":"string"}},{"name":"interface","in":"query","required":false,"description":"Require a machine interface","schema":{"type":"string","enum":["website","api","docs","openapi","mcp","llms_txt","a2a","agent_card","status"]}},{"name":"agent_access","in":"query","required":false,"description":"Only participants with agent access","schema":{"type":"boolean"}},{"name":"verification","in":"query","required":false,"description":"Require a label","schema":{"type":"string","enum":["REGISTERED","OWNERSHIP_VERIFIED","ENDPOINT_VERIFIED","IDENTITY_VERIFIED","CITY_REVIEWED"]}},{"name":"limit","in":"query","required":false,"description":"Page size (1-100, default 20)","schema":{"type":"integer"}},{"name":"offset","in":"query","required":false,"description":"Offset","schema":{"type":"integer"}}],"responses":{"200":{"description":"Participants","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"},"results":{"type":"array","items":{"$ref":"#/components/schemas/Participant"}}}}}}},"400":{"description":"Invalid filter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/participants/{id}":{"get":{"operationId":"getParticipant","summary":"One participant by id or slug","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Participant","content":{"application/json":{"schema":{"type":"object","properties":{"participant":{"$ref":"#/components/schemas/Participant"}}}}}},"404":{"description":"Not found (or not public)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateOwnParticipant","summary":"Update your own participant (management token)","security":[{"managementToken":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfileInput"}}}},"responses":{"200":{"description":"Updated"},"400":{"description":"Invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Bad token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/participants/{id}/verify":{"post":{"operationId":"requestVerificationCheck","summary":"Run an ownership or endpoint check on your own participant","security":[{"managementToken":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["check"],"properties":{"check":{"type":"string","enum":["ownership","endpoint"]}}}}}},"responses":{"200":{"description":"Check result"},"401":{"description":"Bad token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/search":{"get":{"operationId":"searchParticipants","summary":"Search by name, capability, category, use case, keyword, description, language, interface","parameters":[{"name":"q","in":"query","required":false,"description":"Free-text query in any language","schema":{"type":"string"}},{"name":"category","in":"query","required":false,"description":"Category (district) slug","schema":{"type":"string"}},{"name":"capability","in":"query","required":false,"description":"Capability slug","schema":{"type":"string"}},{"name":"type","in":"query","required":false,"description":"Participant type","schema":{"type":"string","enum":["agent-service","api","tool","agent","software-business","digital-business","service-provider","organization","human-operated-business","other"]}},{"name":"language","in":"query","required":false,"description":"BCP 47 language tag the participant supports","schema":{"type":"string"}},{"name":"interface","in":"query","required":false,"description":"Require a machine interface","schema":{"type":"string","enum":["website","api","docs","openapi","mcp","llms_txt","a2a","agent_card","status"]}},{"name":"agent_access","in":"query","required":false,"description":"Only participants with agent access","schema":{"type":"boolean"}},{"name":"verification","in":"query","required":false,"description":"Require a label","schema":{"type":"string","enum":["REGISTERED","OWNERSHIP_VERIFIED","ENDPOINT_VERIFIED","IDENTITY_VERIFIED","CITY_REVIEWED"]}},{"name":"limit","in":"query","required":false,"description":"Page size (1-100, default 20)","schema":{"type":"integer"}},{"name":"offset","in":"query","required":false,"description":"Offset","schema":{"type":"integer"}}],"responses":{"200":{"description":"Participants","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"},"results":{"type":"array","items":{"$ref":"#/components/schemas/Participant"}}}}}}},"400":{"description":"Invalid query","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/participants/register":{"post":{"operationId":"registerParticipant","summary":"Apply to join the city","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProfileInput"},{"type":"object","properties":{"contact_email":{"type":"string","format":"email","description":"Private; never published"}}}]}}}},"responses":{"201":{"description":"Submitted (or registered). Returns management_token once."},"400":{"description":"Invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Duplicate participant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/categories":{"get":{"operationId":"listCategories","summary":"Categories (districts) with counts","responses":{"200":{"description":"Categories"}}}},"/api/v1/capabilities":{"get":{"operationId":"listCapabilities","summary":"Capabilities in use with counts","responses":{"200":{"description":"Capabilities"}}}},"/api/v1/constitution":{"get":{"operationId":"getConstitution","summary":"City rules (structured, versioned)","responses":{"200":{"description":"Constitution"}}}},"/api/v1/health":{"get":{"operationId":"health","summary":"Liveness and configuration (no database access)","responses":{"200":{"description":"OK"}}}}},"components":{"securitySchemes":{"managementToken":{"type":"http","scheme":"bearer","description":"aac_m_... from registration"}},"schemas":{"Participant":{"type":"object","properties":{"id":{"type":"string","example":"p_8x2k..."},"slug":{"type":"string"},"city_id":{"type":"string","example":"america"},"address":{"type":"string","format":"uri"},"name":{"type":"string"},"original_name":{"type":"string"},"original_language":{"type":"string"},"aliases":{"type":"array","items":{"type":"string"}},"short_description":{"type":"string"},"description":{"type":"string"},"participant_type":{"type":"string","enum":["agent-service","api","tool","agent","software-business","digital-business","service-provider","organization","human-operated-business","other"]},"categories":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"}}}},"capabilities":{"type":"array","items":{"type":"string"}},"use_cases":{"type":"array","items":{"type":"string"}},"keywords":{"type":"array","items":{"type":"string"}},"languages":{"type":"array","items":{"type":"string"}},"geographic_scope":{"type":"array","items":{"type":"string"}},"interfaces":{"type":"object","properties":{"website":{"type":"string","format":"uri"},"api":{"type":"string","format":"uri"},"docs":{"type":"string","format":"uri"},"openapi":{"type":"string","format":"uri"},"mcp":{"type":"string","format":"uri"},"llms_txt":{"type":"string","format":"uri"},"a2a":{"type":"string","format":"uri"},"agent_card":{"type":"string","format":"uri"},"status":{"type":"string","format":"uri"}}},"access":{"type":"object","properties":{"human":{"type":"boolean"},"agent":{"type":"boolean"}}},"pricing":{"type":"object","properties":{"summary":{"type":"string"},"url":{"type":"string","format":"uri"},"payment_methods":{"type":"array","items":{"type":"string"}}}},"status":{"type":"object","properties":{"registration":{"type":"string","enum":["DRAFT","SUBMITTED","REGISTERED","REJECTED"]},"operational":{"type":"string","enum":["ACTIVE","SUSPENDED"]}}},"verification":{"type":"object","properties":{"registration":{"type":"string"},"labels":{"type":"array","items":{"type":"string","enum":["REGISTERED","UNVERIFIED","OWNERSHIP_VERIFIED","ENDPOINT_VERIFIED","IDENTITY_VERIFIED","CITY_REVIEWED"]}},"checks":{"type":"object","additionalProperties":{"type":"object"}},"statement":{"type":"string"},"disclaimer":{"type":"string"}}},"links":{"type":"object"},"updated_at":{"type":"string","format":"date-time"}}},"ProfileInput":{"type":"object","required":["display_name","short_description"],"properties":{"display_name":{"type":"string","minLength":2,"maxLength":120},"slug":{"type":"string","pattern":"^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$"},"original_name":{"type":"string"},"original_language":{"type":"string","description":"BCP 47 tag"},"aliases":{"type":"array","items":{"type":"string"}},"short_description":{"type":"string","minLength":10,"maxLength":280},"full_description":{"type":"string","maxLength":4000},"participant_type":{"type":"string","enum":["agent-service","api","tool","agent","software-business","digital-business","service-provider","organization","human-operated-business","other"]},"categories":{"type":"array","items":{"type":"string"},"maxItems":5},"capabilities":{"type":"array","items":{"type":"string"},"maxItems":25},"use_cases":{"type":"array","items":{"type":"string"}},"keywords":{"type":"array","items":{"type":"string"}},"languages":{"type":"array","items":{"type":"string"}},"geographic_scope":{"type":"array","items":{"type":"string"}},"website_url":{"type":"string","format":"uri"},"contact_url":{"type":"string","format":"uri"},"pricing_url":{"type":"string","format":"uri"},"pricing_summary":{"type":"string"},"payment_methods":{"type":"array","items":{"type":"string"}},"human_access_available":{"type":"boolean"},"agent_access_available":{"type":"boolean"},"logo_url":{"type":"string","format":"uri"},"interfaces":{"type":"object","properties":{"api":{"type":"string","format":"uri"},"docs":{"type":"string","format":"uri"},"openapi":{"type":"string","format":"uri"},"mcp":{"type":"string","format":"uri"},"llms_txt":{"type":"string","format":"uri"},"a2a":{"type":"string","format":"uri"},"agent_card":{"type":"string","format":"uri"},"status":{"type":"string","format":"uri"}},"additionalProperties":false},"ownership_disclosure":{"type":"string","maxLength":300},"metadata":{"type":"object"}}},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"retryable":{"type":"boolean"},"details":{"type":"object"}}}}}}}}