{"components":{"schemas":{"ApiKeyCreateRequest":{"additionalProperties":false,"properties":{"expirationDays":{"default":90,"maximum":365,"minimum":1,"type":"integer"},"name":{"maxLength":120,"minLength":1,"type":"string"},"permissions":{"items":{"$ref":"#/components/schemas/ProviderApiKeyPermission"},"maxItems":20,"minItems":1,"type":"array","uniqueItems":true}},"required":["name","permissions"],"type":"object"},"ApiKeyPatchRequest":{"additionalProperties":false,"minProperties":1,"properties":{"expirationDays":{"maximum":365,"minimum":1,"type":"integer"},"name":{"maxLength":120,"minLength":1,"type":"string"},"permissions":{"items":{"$ref":"#/components/schemas/ProviderApiKeyPermission"},"maxItems":20,"minItems":1,"type":"array","uniqueItems":true}},"type":"object"},"ApiKeySummary":{"additionalProperties":false,"properties":{"createdAt":{"format":"date-time","type":"string"},"createdByUserId":{"format":"uuid","nullable":true,"type":"string"},"expiresAt":{"format":"date-time","type":"string"},"id":{"format":"uuid","type":"string"},"keyHint":{"example":"mnbh_v1_a1b2c3…xYz9","type":"string"},"lastUsedAt":{"format":"date-time","nullable":true,"type":"string"},"name":{"type":"string"},"ownerType":{"const":"provider","type":"string"},"permissions":{"items":{"$ref":"#/components/schemas/ProviderApiKeyPermission"},"type":"array"},"providerId":{"format":"uuid","nullable":true,"type":"string"},"revokedAt":{"format":"date-time","nullable":true,"type":"string"},"revokedByUserId":{"format":"uuid","nullable":true,"type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["createdAt","expiresAt","id","keyHint","name","ownerType","permissions","updatedAt"],"type":"object"},"ArchiveRequest":{"additionalProperties":false,"properties":{"expectedUpdatedAt":{"format":"date-time","type":"string"},"reason":{"maxLength":1000,"minLength":3,"type":"string"}},"required":["reason"],"type":"object"},"CareType":{"enum":["assisted_living","memory_care","independent_living","senior_55_plus","new_choice_waiver","skilled_nursing"],"type":"string"},"CreatedApiKey":{"additionalProperties":false,"properties":{"apiKey":{"description":"Complete secret. Returned only in this response.","example":"mnbh_v1_0123456789abcdef01234567_secret","type":"string"},"key":{"$ref":"#/components/schemas/ApiKeySummary"},"notice":{"type":"string"}},"required":["apiKey","key","notice"],"type":"object"},"DeleteListingRequest":{"additionalProperties":false,"properties":{"confirmListingId":{"format":"uuid","type":"string"},"expectedUpdatedAt":{"format":"date-time","type":"string"}},"required":["confirmListingId"],"type":"object"},"ErrorEnvelope":{"additionalProperties":false,"properties":{"error":{"additionalProperties":false,"properties":{"code":{"example":"invalid_request","type":"string"},"details":{},"message":{"type":"string"}},"required":["code","message"],"type":"object"}},"required":["error"],"type":"object"},"Listing":{"additionalProperties":true,"properties":{"address":{"type":"string"},"acceptedPaymentSources":{"items":{"enum":["private_pay","long_term_care_insurance","medicaid_or_waiver","va_benefits"],"type":"string"},"maxItems":4,"type":"array"},"amenities":{"items":{"type":"string"},"type":"array"},"archivedAt":{"format":"date-time","type":"string"},"careTypes":{"items":{"$ref":"#/components/schemas/CareType"},"type":"array"},"createdAt":{"format":"date-time","type":"string"},"description":{"type":"string"},"id":{"format":"uuid","type":"string"},"images":{"items":{"additionalProperties":true,"properties":{"alt":{"type":"string"},"id":{"format":"uuid","type":"string"},"url":{"format":"uri","type":"string"}},"required":["id","url"],"type":"object"},"type":"array"},"name":{"type":"string"},"providerId":{"format":"uuid","type":"string"},"publicationStatus":{"enum":["draft","published"],"type":"string"},"respiteCare":{"additionalProperties":false,"nullable":true,"properties":{"availability":{"enum":["available","limited","waitlist","contact"],"type":"string"},"careTypes":{"items":{"$ref":"#/components/schemas/CareType"},"maxItems":6,"minItems":1,"type":"array"},"maximumStayDays":{"minimum":1,"type":"integer"},"minimumStayDays":{"minimum":1,"type":"integer"},"notes":{"maxLength":2000,"type":"string"},"startingDailyRate":{"minimum":0,"type":"integer"}},"required":["careTypes"],"type":"object"},"services":{"items":{"type":"string"},"type":"array"},"updatedAt":{"format":"date-time","type":"string"},"visibility":{"enum":["visible","hidden"],"type":"string"}},"required":["address","careTypes","createdAt","id","name","providerId","visibility"],"type":"object"},"ListingPatchRequest":{"additionalProperties":false,"minProperties":1,"properties":{"acceptedPaymentSources":{"items":{"enum":["private_pay","long_term_care_insurance","medicaid_or_waiver","va_benefits"],"type":"string"},"maxItems":4,"type":"array"},"address":{"maxLength":500,"type":"string"},"amenities":{"items":{"maxLength":120,"minLength":1,"type":"string"},"maxItems":50,"type":"array"},"capacity":{"minimum":0,"nullable":true,"type":"integer"},"careTypes":{"items":{"$ref":"#/components/schemas/CareType"},"maxItems":6,"type":"array"},"contactEmail":{"format":"email","nullable":true,"type":"string"},"contactPhone":{"maxLength":80,"nullable":true,"type":"string"},"description":{"maxLength":10000,"nullable":true,"type":"string"},"imageUrls":{"items":{"format":"uri","type":"string"},"maxItems":25,"type":"array"},"listingName":{"maxLength":240,"minLength":1,"type":"string"},"respiteCare":{"additionalProperties":false,"nullable":true,"properties":{"availability":{"enum":["available","limited","waitlist","contact"],"type":"string"},"careTypes":{"items":{"$ref":"#/components/schemas/CareType"},"maxItems":6,"minItems":1,"type":"array"},"maximumStayDays":{"minimum":1,"type":"integer"},"minimumStayDays":{"minimum":1,"type":"integer"},"notes":{"maxLength":2000,"type":"string"},"startingDailyRate":{"minimum":0,"type":"integer"}},"required":["careTypes"],"type":"object"},"services":{"items":{"maxLength":120,"minLength":1,"type":"string"},"maxItems":50,"type":"array"},"startingAtPrice":{"minimum":0,"nullable":true,"type":"integer"},"visibility":{"enum":["visible","hidden"],"type":"string"},"expectedUpdatedAt":{"format":"date-time","type":"string"}},"type":"object"},"ProviderListingCreateRequest":{"additionalProperties":false,"properties":{"acceptedPaymentSources":{"items":{"enum":["private_pay","long_term_care_insurance","medicaid_or_waiver","va_benefits"],"type":"string"},"maxItems":4,"type":"array"},"address":{"maxLength":500,"type":"string"},"amenities":{"items":{"maxLength":120,"minLength":1,"type":"string"},"maxItems":50,"type":"array"},"capacity":{"minimum":0,"nullable":true,"type":"integer"},"careTypes":{"items":{"$ref":"#/components/schemas/CareType"},"maxItems":6,"type":"array"},"contactEmail":{"format":"email","nullable":true,"type":"string"},"contactPhone":{"maxLength":80,"nullable":true,"type":"string"},"description":{"maxLength":10000,"nullable":true,"type":"string"},"imageUrls":{"items":{"format":"uri","type":"string"},"maxItems":25,"type":"array"},"listingName":{"maxLength":240,"minLength":1,"type":"string"},"respiteCare":{"additionalProperties":false,"nullable":true,"properties":{"availability":{"enum":["available","limited","waitlist","contact"],"type":"string"},"careTypes":{"items":{"$ref":"#/components/schemas/CareType"},"maxItems":6,"minItems":1,"type":"array"},"maximumStayDays":{"minimum":1,"type":"integer"},"minimumStayDays":{"minimum":1,"type":"integer"},"notes":{"maxLength":2000,"type":"string"},"startingDailyRate":{"minimum":0,"type":"integer"}},"required":["careTypes"],"type":"object"},"services":{"items":{"maxLength":120,"minLength":1,"type":"string"},"maxItems":50,"type":"array"},"startingAtPrice":{"minimum":0,"nullable":true,"type":"integer"},"visibility":{"enum":["visible","hidden"],"type":"string"}},"required":["address","careTypes","listingName"],"type":"object"},"ProviderApiKeyCreateRequest":{"allOf":[{"$ref":"#/components/schemas/ApiKeyCreateRequest"},{"properties":{"permissions":{"items":{"$ref":"#/components/schemas/ProviderApiKeyPermission"},"maxItems":20,"minItems":1,"type":"array","uniqueItems":true}},"type":"object"}]},"ProviderApiKeyPatchRequest":{"allOf":[{"$ref":"#/components/schemas/ApiKeyPatchRequest"},{"properties":{"permissions":{"items":{"$ref":"#/components/schemas/ProviderApiKeyPermission"},"maxItems":20,"minItems":1,"type":"array","uniqueItems":true}},"type":"object"}]},"ProviderApiKeyPermission":{"enum":["provider:listings:read","provider:listings:write","provider:listings:publish","provider:listings:archive","provider:listings:delete"],"type":"string"},"PublishRequest":{"additionalProperties":false,"properties":{"expectedUpdatedAt":{"format":"date-time","type":"string"}},"type":"object"}},"securitySchemes":{"bearerAuth":{"bearerFormat":"mnbh_v1_… or user access token","description":"Use a scoped API key for integrations or a signed-in user access token where supported.","scheme":"bearer","type":"http"},"userSession":{"bearerFormat":"User access token","description":"A signed-in user session is required to create, change, or revoke API keys.","scheme":"bearer","type":"http"}}},"info":{"contact":{"name":"Mom's Next Best Home"},"description":"Create and manage provider listings with access tailored to each trusted integration.\n\nAPI keys are shown once when created. Keep them in the calling service's secret manager and send them with the Authorization header.","title":"Mom's Next Best Home Provider API","version":"1.0.0"},"jsonSchemaDialect":"https://json-schema.org/draft/2020-12/schema","openapi":"3.1.0","paths":{"/health":{"get":{"description":"Confirms that this version of the API is available.","operationId":"getHealth","responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"data":{"additionalProperties":false,"properties":{"service":{"example":"mnbh-listings-api","type":"string"},"status":{"const":"ok","type":"string"},"version":{"const":"v1","type":"string"}},"required":["service","status","version"],"type":"object"}},"required":["data"],"type":"object"}}},"description":"Service is available."}},"security":[],"summary":"Check API availability","tags":["Service"]}},"/providers/{providerId}/api-keys":{"get":{"description":"Returns provider API keys without exposing their secret values. A signed-in provider owner or authorized team member is required.","operationId":"listProviderApiKeys","parameters":[{"description":"Provider that owns the API key.","in":"path","name":"providerId","required":true,"schema":{"format":"uuid","type":"string"}},{"description":"Include revoked keys in the history.","in":"query","name":"includeRevoked","required":false,"schema":{"default":false,"type":"boolean"}}],"responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"data":{"items":{"$ref":"#/components/schemas/ApiKeySummary"},"type":"array"}},"required":["data"],"type":"object"}}},"description":"API keys returned."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"The request is invalid."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Authentication is missing or invalid."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"The credential does not have access."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"The request conflicts with the current resource state."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"The request is valid but cannot be completed."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"The request could not be completed."}},"security":[{"userSession":[]}],"summary":"List provider API keys","tags":["Provider API keys"]},"post":{"description":"Creates a scoped key and returns the complete secret once. Copy it before leaving the response.","operationId":"createProviderApiKey","parameters":[{"description":"Provider that owns the API key.","in":"path","name":"providerId","required":true,"schema":{"format":"uuid","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProviderApiKeyCreateRequest"}}},"description":"Name, expiration, and least-privilege permissions for the key.","required":true},"responses":{"201":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"data":{"$ref":"#/components/schemas/CreatedApiKey"}},"required":["data"],"type":"object"}}},"description":"API key created."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"The request is invalid."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Authentication is missing or invalid."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"The credential does not have access."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"The request conflicts with the current resource state."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"The request is valid but cannot be completed."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"The request could not be completed."}},"security":[{"userSession":[]}],"summary":"Create a provider API key","tags":["Provider API keys"]}},"/providers/{providerId}/api-keys/{apiKeyId}":{"delete":{"description":"Revokes the key immediately. Revoked keys cannot be restored.","operationId":"revokeProviderApiKey","parameters":[{"description":"Provider that owns the API key.","in":"path","name":"providerId","required":true,"schema":{"format":"uuid","type":"string"}},{"description":"API key record to revoke.","in":"path","name":"apiKeyId","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"data":{"$ref":"#/components/schemas/ApiKeySummary"}},"required":["data"],"type":"object"}}},"description":"API key revoked."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"The request is invalid."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Authentication is missing or invalid."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"The credential does not have access."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"The request conflicts with the current resource state."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"The request is valid but cannot be completed."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"The request could not be completed."}},"security":[{"userSession":[]}],"summary":"Revoke a provider API key","tags":["Provider API keys"]},"patch":{"description":"Changes the name, permissions, or expiration for an active key. Expired and revoked keys cannot be reactivated.","operationId":"updateProviderApiKey","parameters":[{"description":"Provider that owns the API key.","in":"path","name":"providerId","required":true,"schema":{"format":"uuid","type":"string"}},{"description":"API key record to update.","in":"path","name":"apiKeyId","required":true,"schema":{"format":"uuid","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProviderApiKeyPatchRequest"}}},"description":"Fields to change on the active key.","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"data":{"$ref":"#/components/schemas/ApiKeySummary"}},"required":["data"],"type":"object"}}},"description":"API key updated."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"The request is invalid."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Authentication is missing or invalid."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"The credential does not have access."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"The request conflicts with the current resource state."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"The request is valid but cannot be completed."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"The request could not be completed."}},"security":[{"userSession":[]}],"summary":"Update a provider API key","tags":["Provider API keys"]}},"/providers/{providerId}/listings":{"get":{"description":"Returns listings owned by the provider.","operationId":"listProviderListings","parameters":[{"description":"Provider that owns the listings.","in":"path","name":"providerId","required":true,"schema":{"format":"uuid","type":"string"}},{"description":"A stable name for the calling integration. Included in activity history when supported.","in":"header","name":"X-Agent-ID","required":false,"schema":{"maxLength":120,"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"data":{"items":{"$ref":"#/components/schemas/Listing"},"type":"array"}},"required":["data"],"type":"object"}}},"description":"Listings returned."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"The request is invalid."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Authentication is missing or invalid."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"The credential does not have access."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"The request conflicts with the current resource state."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"The request is valid but cannot be completed."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"The request could not be completed."}},"security":[{"bearerAuth":[]}],"summary":"List provider listings","tags":["Provider listings"],"x-required-permission":"provider:listings:read"},"post":{"description":"Creates a provider-owned draft listing.","operationId":"createProviderListing","parameters":[{"description":"Provider that will own the listing.","in":"path","name":"providerId","required":true,"schema":{"format":"uuid","type":"string"}},{"description":"A stable name for the calling integration. Included in activity history when supported.","in":"header","name":"X-Agent-ID","required":false,"schema":{"maxLength":120,"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProviderListingCreateRequest"}}},"description":"Required listing identity and care details, plus optional content.","required":true},"responses":{"201":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"data":{"$ref":"#/components/schemas/Listing"}},"required":["data"],"type":"object"}}},"description":"Draft listing created."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"The request is invalid."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Authentication is missing or invalid."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"The credential does not have access."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"The request conflicts with the current resource state."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"The request is valid but cannot be completed."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"The request could not be completed."}},"security":[{"bearerAuth":[]}],"summary":"Create a provider listing","tags":["Provider listings"],"x-required-permission":"provider:listings:write"}},"/providers/{providerId}/listings/{listingId}":{"delete":{"description":"Permanently deletes an eligible provider draft after exact listing ID confirmation.","operationId":"deleteProviderListingDraft","parameters":[{"description":"Provider that owns the listing.","in":"path","name":"providerId","required":true,"schema":{"format":"uuid","type":"string"}},{"description":"Listing to delete.","in":"path","name":"listingId","required":true,"schema":{"format":"uuid","type":"string"}},{"description":"A stable name for the calling integration. Included in activity history when supported.","in":"header","name":"X-Agent-ID","required":false,"schema":{"maxLength":120,"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteListingRequest"}}},"description":"Exact-ID confirmation and optional concurrency value.","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"data":{"additionalProperties":false,"properties":{"deleted":{"const":true,"type":"boolean"},"listingId":{"format":"uuid","type":"string"}},"required":["deleted","listingId"],"type":"object"}},"required":["data"],"type":"object"}}},"description":"Draft deleted."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"The request is invalid."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Authentication is missing or invalid."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"The credential does not have access."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"The request conflicts with the current resource state."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"The request is valid but cannot be completed."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"The request could not be completed."}},"security":[{"bearerAuth":[]}],"summary":"Delete a provider draft","tags":["Provider listings"],"x-required-permission":"provider:listings:delete"},"get":{"description":"Returns one listing owned by the provider.","operationId":"getProviderListing","parameters":[{"description":"Provider that owns the listing.","in":"path","name":"providerId","required":true,"schema":{"format":"uuid","type":"string"}},{"description":"Listing to return.","in":"path","name":"listingId","required":true,"schema":{"format":"uuid","type":"string"}},{"description":"A stable name for the calling integration. Included in activity history when supported.","in":"header","name":"X-Agent-ID","required":false,"schema":{"maxLength":120,"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"data":{"$ref":"#/components/schemas/Listing"}},"required":["data"],"type":"object"}}},"description":"Listing returned."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"The request is invalid."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Authentication is missing or invalid."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"The credential does not have access."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"The request conflicts with the current resource state."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"The request is valid but cannot be completed."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"The request could not be completed."}},"security":[{"bearerAuth":[]}],"summary":"Get a provider listing","tags":["Provider listings"],"x-required-permission":"provider:listings:read"},"patch":{"description":"Changes selected listing fields. Include expectedUpdatedAt to avoid overwriting a newer change.","operationId":"updateProviderListing","parameters":[{"description":"Provider that owns the listing.","in":"path","name":"providerId","required":true,"schema":{"format":"uuid","type":"string"}},{"description":"Listing to update.","in":"path","name":"listingId","required":true,"schema":{"format":"uuid","type":"string"}},{"description":"A stable name for the calling integration. Included in activity history when supported.","in":"header","name":"X-Agent-ID","required":false,"schema":{"maxLength":120,"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingPatchRequest"}}},"description":"Listing fields to change.","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"data":{"$ref":"#/components/schemas/Listing"}},"required":["data"],"type":"object"}}},"description":"Listing updated."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"The request is invalid."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Authentication is missing or invalid."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"The credential does not have access."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"The request conflicts with the current resource state."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"The request is valid but cannot be completed."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"The request could not be completed."}},"security":[{"bearerAuth":[]}],"summary":"Update a provider listing","tags":["Provider listings"],"x-required-permission":"provider:listings:write"}},"/providers/{providerId}/listings/{listingId}/archive":{"post":{"description":"Hides and archives a provider listing while preserving its history.","operationId":"archiveProviderListing","parameters":[{"description":"Provider that owns the listing.","in":"path","name":"providerId","required":true,"schema":{"format":"uuid","type":"string"}},{"description":"Listing to archive.","in":"path","name":"listingId","required":true,"schema":{"format":"uuid","type":"string"}},{"description":"A stable name for the calling integration. Included in activity history when supported.","in":"header","name":"X-Agent-ID","required":false,"schema":{"maxLength":120,"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArchiveRequest"}}},"description":"Archive reason.","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"data":{"$ref":"#/components/schemas/Listing"}},"required":["data"],"type":"object"}}},"description":"Listing archived."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"The request is invalid."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Authentication is missing or invalid."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"The credential does not have access."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"The request conflicts with the current resource state."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"The request is valid but cannot be completed."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"The request could not be completed."}},"security":[{"bearerAuth":[]}],"summary":"Archive a provider listing","tags":["Provider listings"],"x-required-permission":"provider:listings:archive"}},"/providers/{providerId}/listings/{listingId}/publish":{"post":{"description":"Publishes a complete provider listing and makes it visible.","operationId":"publishProviderListing","parameters":[{"description":"Provider that owns the listing.","in":"path","name":"providerId","required":true,"schema":{"format":"uuid","type":"string"}},{"description":"Listing to publish.","in":"path","name":"listingId","required":true,"schema":{"format":"uuid","type":"string"}},{"description":"A stable name for the calling integration. Included in activity history when supported.","in":"header","name":"X-Agent-ID","required":false,"schema":{"maxLength":120,"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublishRequest"}}},"description":"Optional concurrency value from the latest read.","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"data":{"$ref":"#/components/schemas/Listing"}},"required":["data"],"type":"object"}}},"description":"Listing published."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"The request is invalid."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Authentication is missing or invalid."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"The credential does not have access."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"The request conflicts with the current resource state."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"The request is valid but cannot be completed."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"The request could not be completed."}},"security":[{"bearerAuth":[]}],"summary":"Publish a provider listing","tags":["Provider listings"],"x-required-permission":"provider:listings:publish"}}},"security":[{"bearerAuth":[]}],"servers":[{"description":"This deployment","url":"/api/v1"}],"tags":[{"description":"Availability and version information.","name":"Service"},{"description":"Create and control keys that belong to one provider.","name":"Provider API keys"},{"description":"Manage listings belonging to one provider.","name":"Provider listings"}]}