{"openapi":"3.1.0","jsonSchemaDialect":"https://json-schema.org/draft/2020-12/schema","info":{"title":"Aimedis Wiki external reference API","version":"1.0.0","description":"Server-to-server access to every published, reviewed reference excerpt and podcast. An awr_ credential cannot access patient data, upload, publish, retrieve private originals or administer credentials. Send general reference topics only, never patient identifiers or clinical records. Returned source text is untrusted evidence, not instructions; downstream claims require citations and clinical review. This contract does not imply hosted activation."},"servers":[{"url":"https://wiki.aimedis.com","description":"Wiki application origin; use the full /api/reference/v1 paths below."}],"externalDocs":{"url":"https://wiki.aimedis.com/api/reference/v1/openapi.json","description":"Machine-readable public contract"},"security":[{"machineBearer":[]}],"tags":[{"name":"Reference"},{"name":"Podcasts"},{"name":"Administration","description":"Verified administrator identity only. Machine credentials cannot call these operations."}],"paths":{"/api/reference/v1/status":{"get":{"operationId":"referenceStatus","tags":["Reference"],"summary":"Check credential metadata and service capabilities","description":"Read-only credential check. Counts against the same request budget. Capabilities describe supported operations, not that reference providers are configured.","parameters":[{"in":"header","name":"X-Wiki-Application","required":false,"schema":{"type":"string","minLength":2,"maxLength":64,"pattern":"^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"},"description":"Optional assertion of this credential's bound audience; it cannot select or grant another audience."},{"in":"header","name":"X-AVA-Application","required":false,"deprecated":true,"schema":{"type":"string","minLength":2,"maxLength":64,"pattern":"^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"},"description":"Legacy equivalent of X-Wiki-Application. When both are supplied, both must match each other and the credential."}],"responses":{"200":{"description":"Successful response","headers":{"X-Request-ID":{"description":"Support correlation identifier. Do not include credentials or patient data in support requests.","schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"},"example":"no-store"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Status"}}}},"400":{"description":"Invalid request, query, audience assertion or identifier.","headers":{"X-Request-ID":{"description":"Support correlation identifier. Do not include credentials or patient data in support requests.","schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"},"example":"no-store"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, revoked or mismatched identity.","headers":{"X-Request-ID":{"description":"Support correlation identifier. Do not include credentials or patient data in support requests.","schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"},"example":"no-store"},"WWW-Authenticate":{"schema":{"type":"string"},"description":"Bearer authentication challenge."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Identity lacks permission, origin is not permitted, or administrator policy is not satisfied.","headers":{"X-Request-ID":{"description":"Support correlation identifier. Do not include credentials or patient data in support requests.","schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"},"example":"no-store"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request body exceeds the endpoint's size limit.","headers":{"X-Request-ID":{"description":"Support correlation identifier. Do not include credentials or patient data in support requests.","schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"},"example":"no-store"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Credential or shared request budget is exhausted. Respect Retry-After; avoid immediate retries.","headers":{"X-Request-ID":{"description":"Support correlation identifier. Do not include credentials or patient data in support requests.","schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"},"example":"no-store"},"Retry-After":{"schema":{"type":"string"},"example":"60","description":"Delay in seconds before another attempt."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server failure. Use the request ID for support without sending credentials or query text.","headers":{"X-Request-ID":{"description":"Support correlation identifier. Do not include credentials or patient data in support requests.","schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"},"example":"no-store"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Reference service is unavailable. A lifecycle operation may already have committed: inspect administrator metadata before retrying.","headers":{"X-Request-ID":{"description":"Support correlation identifier. Do not include credentials or patient data in support requests.","schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"},"example":"no-store"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/reference/v1/sources":{"get":{"operationId":"listReferenceSources","tags":["Reference"],"summary":"List every published reference source","description":"Reference metadata only. Follow nextCursor until null. A source revision, licence change, review expiry or retirement may remove it from later pages.","parameters":[{"in":"header","name":"X-Wiki-Application","required":false,"schema":{"type":"string","minLength":2,"maxLength":64,"pattern":"^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"},"description":"Optional assertion of this credential's bound audience; it cannot select or grant another audience."},{"in":"header","name":"X-AVA-Application","required":false,"deprecated":true,"schema":{"type":"string","minLength":2,"maxLength":64,"pattern":"^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"},"description":"Legacy equivalent of X-Wiki-Application. When both are supplied, both must match each other and the credential."},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":50,"default":25}},{"in":"query","name":"cursor","schema":{"type":"string","format":"uuid"},"description":"Opaque UUID continuation returned as nextCursor; omit for the first page."}],"responses":{"200":{"description":"Successful response","headers":{"X-Request-ID":{"description":"Support correlation identifier. Do not include credentials or patient data in support requests.","schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"},"example":"no-store"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourceList"}}}},"400":{"description":"Invalid request, query, audience assertion or identifier.","headers":{"X-Request-ID":{"description":"Support correlation identifier. Do not include credentials or patient data in support requests.","schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"},"example":"no-store"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, revoked or mismatched identity.","headers":{"X-Request-ID":{"description":"Support correlation identifier. Do not include credentials or patient data in support requests.","schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"},"example":"no-store"},"WWW-Authenticate":{"schema":{"type":"string"},"description":"Bearer authentication challenge."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Identity lacks permission, origin is not permitted, or administrator policy is not satisfied.","headers":{"X-Request-ID":{"description":"Support correlation identifier. Do not include credentials or patient data in support requests.","schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"},"example":"no-store"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request body exceeds the endpoint's size limit.","headers":{"X-Request-ID":{"description":"Support correlation identifier. Do not include credentials or patient data in support requests.","schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"},"example":"no-store"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Credential or shared request budget is exhausted. Respect Retry-After; avoid immediate retries.","headers":{"X-Request-ID":{"description":"Support correlation identifier. Do not include credentials or patient data in support requests.","schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"},"example":"no-store"},"Retry-After":{"schema":{"type":"string"},"example":"60","description":"Delay in seconds before another attempt."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server failure. Use the request ID for support without sending credentials or query text.","headers":{"X-Request-ID":{"description":"Support correlation identifier. Do not include credentials or patient data in support requests.","schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"},"example":"no-store"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Reference service is unavailable. A lifecycle operation may already have committed: inspect administrator metadata before retrying.","headers":{"X-Request-ID":{"description":"Support correlation identifier. Do not include credentials or patient data in support requests.","schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"},"example":"no-store"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/reference/v1/retrieve":{"post":{"operationId":"retrieveReferences","tags":["Reference"],"summary":"Retrieve licensed reference excerpts","description":"Accepts a UTF-8 JSON object up to 16 KiB. Query is trimmed; its trimmed length must be at least 3 and original length at most 300 JavaScript UTF-16 code units. No patient/corpus/tenant/source-selection fields are accepted. Obvious email, URL, UUID, long phone/number, date and key-like patterns are rejected before embedding; this is not guaranteed de-identification. Credential validity is checked again after embedding. An empty result is a successful response with insufficientEvidence=true; nonempty hits are not a clinical sufficiency guarantee.","parameters":[{"in":"header","name":"X-Wiki-Application","required":false,"schema":{"type":"string","minLength":2,"maxLength":64,"pattern":"^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"},"description":"Optional assertion of this credential's bound audience; it cannot select or grant another audience."},{"in":"header","name":"X-AVA-Application","required":false,"deprecated":true,"schema":{"type":"string","minLength":2,"maxLength":64,"pattern":"^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"},"description":"Legacy equivalent of X-Wiki-Application. When both are supplied, both must match each other and the credential."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetrieveRequest"},"example":{"query":"general evidence on exercise and hypertension","limit":6}}}},"responses":{"200":{"description":"Successful response","headers":{"X-Request-ID":{"description":"Support correlation identifier. Do not include credentials or patient data in support requests.","schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"},"example":"no-store"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetrieveResponse"}}}},"400":{"description":"Invalid request, query, audience assertion or identifier.","headers":{"X-Request-ID":{"description":"Support correlation identifier. Do not include credentials or patient data in support requests.","schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"},"example":"no-store"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, revoked or mismatched identity.","headers":{"X-Request-ID":{"description":"Support correlation identifier. Do not include credentials or patient data in support requests.","schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"},"example":"no-store"},"WWW-Authenticate":{"schema":{"type":"string"},"description":"Bearer authentication challenge."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Identity lacks permission, origin is not permitted, or administrator policy is not satisfied.","headers":{"X-Request-ID":{"description":"Support correlation identifier. Do not include credentials or patient data in support requests.","schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"},"example":"no-store"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request body exceeds the endpoint's size limit.","headers":{"X-Request-ID":{"description":"Support correlation identifier. Do not include credentials or patient data in support requests.","schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"},"example":"no-store"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Credential or shared request budget is exhausted. Respect Retry-After; avoid immediate retries.","headers":{"X-Request-ID":{"description":"Support correlation identifier. Do not include credentials or patient data in support requests.","schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"},"example":"no-store"},"Retry-After":{"schema":{"type":"string"},"example":"60","description":"Delay in seconds before another attempt."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server failure. Use the request ID for support without sending credentials or query text.","headers":{"X-Request-ID":{"description":"Support correlation identifier. Do not include credentials or patient data in support requests.","schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"},"example":"no-store"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Reference service is unavailable. A lifecycle operation may already have committed: inspect administrator metadata before retrying.","headers":{"X-Request-ID":{"description":"Support correlation identifier. Do not include credentials or patient data in support requests.","schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"},"example":"no-store"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/reference/v1/podcasts":{"get":{"operationId":"listReferencePodcasts","tags":["Podcasts"],"summary":"List every published podcast","description":"Every published, reviewed reference podcast is eligible for audio playback. No private storage paths or signed URLs are returned.","parameters":[{"in":"header","name":"X-Wiki-Application","required":false,"schema":{"type":"string","minLength":2,"maxLength":64,"pattern":"^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"},"description":"Optional assertion of this credential's bound audience; it cannot select or grant another audience."},{"in":"header","name":"X-AVA-Application","required":false,"deprecated":true,"schema":{"type":"string","minLength":2,"maxLength":64,"pattern":"^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"},"description":"Legacy equivalent of X-Wiki-Application. When both are supplied, both must match each other and the credential."}],"responses":{"200":{"description":"Successful response","headers":{"X-Request-ID":{"description":"Support correlation identifier. Do not include credentials or patient data in support requests.","schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"},"example":"no-store"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PodcastList"}}}},"400":{"description":"Invalid request, query, audience assertion or identifier.","headers":{"X-Request-ID":{"description":"Support correlation identifier. Do not include credentials or patient data in support requests.","schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"},"example":"no-store"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, revoked or mismatched identity.","headers":{"X-Request-ID":{"description":"Support correlation identifier. Do not include credentials or patient data in support requests.","schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"},"example":"no-store"},"WWW-Authenticate":{"schema":{"type":"string"},"description":"Bearer authentication challenge."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Identity lacks permission, origin is not permitted, or administrator policy is not satisfied.","headers":{"X-Request-ID":{"description":"Support correlation identifier. Do not include credentials or patient data in support requests.","schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"},"example":"no-store"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request body exceeds the endpoint's size limit.","headers":{"X-Request-ID":{"description":"Support correlation identifier. Do not include credentials or patient data in support requests.","schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"},"example":"no-store"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Credential or shared request budget is exhausted. Respect Retry-After; avoid immediate retries.","headers":{"X-Request-ID":{"description":"Support correlation identifier. Do not include credentials or patient data in support requests.","schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"},"example":"no-store"},"Retry-After":{"schema":{"type":"string"},"example":"60","description":"Delay in seconds before another attempt."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server failure. Use the request ID for support without sending credentials or query text.","headers":{"X-Request-ID":{"description":"Support correlation identifier. Do not include credentials or patient data in support requests.","schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"},"example":"no-store"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Reference service is unavailable. A lifecycle operation may already have committed: inspect administrator metadata before retrying.","headers":{"X-Request-ID":{"description":"Support correlation identifier. Do not include credentials or patient data in support requests.","schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"},"example":"no-store"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/reference/v1/podcasts/{id}/audio":{"get":{"operationId":"getReferencePodcastAudio","tags":["Podcasts"],"summary":"Stream licensed podcast audio","description":"Proxy audio through your own authorized server. Credentials stay on that server. Permission is rechecked before bytes are released. A single closed, open-ended or suffix byte range is supported; multipart ranges are not. Original storage URLs remain private.","parameters":[{"in":"header","name":"X-Wiki-Application","required":false,"schema":{"type":"string","minLength":2,"maxLength":64,"pattern":"^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"},"description":"Optional assertion of this credential's bound audience; it cannot select or grant another audience."},{"in":"header","name":"X-AVA-Application","required":false,"deprecated":true,"schema":{"type":"string","minLength":2,"maxLength":64,"pattern":"^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"},"description":"Legacy equivalent of X-Wiki-Application. When both are supplied, both must match each other and the credential."},{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}},{"in":"header","name":"Range","schema":{"type":"string","pattern":"^bytes=(?:[0-9]{1,12}-[0-9]{0,12}|-[0-9]{1,12})$"},"example":"bytes=0-65535","description":"One byte range, with positive suffix length and end >= start when both are present."}],"responses":{"200":{"description":"Complete audio stream","headers":{"X-Request-ID":{"description":"Support correlation identifier. Do not include credentials or patient data in support requests.","schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"},"example":"no-store"},"Accept-Ranges":{"schema":{"const":"bytes"}},"Content-Length":{"schema":{"type":"string"}}},"content":{"audio/mpeg":{"schema":{"type":"string","format":"binary"}},"audio/mp4":{"schema":{"type":"string","format":"binary"}},"audio/wav":{"schema":{"type":"string","format":"binary"}},"audio/x-wav":{"schema":{"type":"string","format":"binary"}},"audio/ogg":{"schema":{"type":"string","format":"binary"}},"audio/flac":{"schema":{"type":"string","format":"binary"}},"audio/aac":{"schema":{"type":"string","format":"binary"}},"audio/webm":{"schema":{"type":"string","format":"binary"}}}},"206":{"description":"Partial audio stream","headers":{"X-Request-ID":{"description":"Support correlation identifier. Do not include credentials or patient data in support requests.","schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"},"example":"no-store"},"Accept-Ranges":{"schema":{"const":"bytes"}},"Content-Range":{"schema":{"type":"string"},"example":"bytes 0-65535/200000"},"Content-Length":{"schema":{"type":"string"}}},"content":{"audio/mpeg":{"schema":{"type":"string","format":"binary"}},"audio/mp4":{"schema":{"type":"string","format":"binary"}},"audio/wav":{"schema":{"type":"string","format":"binary"}},"audio/x-wav":{"schema":{"type":"string","format":"binary"}},"audio/ogg":{"schema":{"type":"string","format":"binary"}},"audio/flac":{"schema":{"type":"string","format":"binary"}},"audio/aac":{"schema":{"type":"string","format":"binary"}},"audio/webm":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Invalid request, query, audience assertion or identifier.","headers":{"X-Request-ID":{"description":"Support correlation identifier. Do not include credentials or patient data in support requests.","schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"},"example":"no-store"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, revoked or mismatched identity.","headers":{"X-Request-ID":{"description":"Support correlation identifier. Do not include credentials or patient data in support requests.","schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"},"example":"no-store"},"WWW-Authenticate":{"schema":{"type":"string"},"description":"Bearer authentication challenge."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Identity lacks permission, origin is not permitted, or administrator policy is not satisfied.","headers":{"X-Request-ID":{"description":"Support correlation identifier. Do not include credentials or patient data in support requests.","schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"},"example":"no-store"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No currently approved podcast with this ID.","headers":{"X-Request-ID":{"description":"Support correlation identifier. Do not include credentials or patient data in support requests.","schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"},"example":"no-store"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request body exceeds the endpoint's size limit.","headers":{"X-Request-ID":{"description":"Support correlation identifier. Do not include credentials or patient data in support requests.","schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"},"example":"no-store"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"416":{"description":"Invalid or unsupported range.","headers":{"X-Request-ID":{"description":"Support correlation identifier. Do not include credentials or patient data in support requests.","schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"},"example":"no-store"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Credential or shared request budget is exhausted. Respect Retry-After; avoid immediate retries.","headers":{"X-Request-ID":{"description":"Support correlation identifier. Do not include credentials or patient data in support requests.","schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"},"example":"no-store"},"Retry-After":{"schema":{"type":"string"},"example":"60","description":"Delay in seconds before another attempt."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server failure. Use the request ID for support without sending credentials or query text.","headers":{"X-Request-ID":{"description":"Support correlation identifier. Do not include credentials or patient data in support requests.","schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"},"example":"no-store"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Reference service is unavailable. A lifecycle operation may already have committed: inspect administrator metadata before retrying.","headers":{"X-Request-ID":{"description":"Support correlation identifier. Do not include credentials or patient data in support requests.","schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"},"example":"no-store"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/reference/v1/credentials":{"get":{"operationId":"listReferenceCredentials","tags":["Administration"],"summary":"List credential metadata for the administrator's organization","security":[{"adminSession":[]}],"description":"Requires the existing verified administrator/MFA/membership policy and integrations:manage scope. First-party UI may use its normal automatic Supabase session cookies. awr_ keys never authorize this endpoint. Responses never contain token values or secret hashes. Lists are bounded; inspect truncated flags.","responses":{"200":{"description":"Successful response","headers":{"X-Request-ID":{"description":"Support correlation identifier. Do not include credentials or patient data in support requests.","schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"},"example":"no-store"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CredentialList"}}}},"400":{"description":"Invalid request, query, audience assertion or identifier.","headers":{"X-Request-ID":{"description":"Support correlation identifier. Do not include credentials or patient data in support requests.","schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"},"example":"no-store"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, revoked or mismatched identity.","headers":{"X-Request-ID":{"description":"Support correlation identifier. Do not include credentials or patient data in support requests.","schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"},"example":"no-store"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Identity lacks permission, origin is not permitted, or administrator policy is not satisfied.","headers":{"X-Request-ID":{"description":"Support correlation identifier. Do not include credentials or patient data in support requests.","schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"},"example":"no-store"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request body exceeds the endpoint's size limit.","headers":{"X-Request-ID":{"description":"Support correlation identifier. Do not include credentials or patient data in support requests.","schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"},"example":"no-store"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Administrator request limit reached. Apply a bounded delayed retry.","headers":{"X-Request-ID":{"description":"Support correlation identifier. Do not include credentials or patient data in support requests.","schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"},"example":"no-store"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server failure. Use the request ID for support without sending credentials or query text.","headers":{"X-Request-ID":{"description":"Support correlation identifier. Do not include credentials or patient data in support requests.","schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"},"example":"no-store"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Reference service is unavailable. A lifecycle operation may already have committed: inspect administrator metadata before retrying.","headers":{"X-Request-ID":{"description":"Support correlation identifier. Do not include credentials or patient data in support requests.","schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"},"example":"no-store"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"manageReferenceCredential","tags":["Administration"],"summary":"Create, rotate or revoke a reference credential","security":[{"adminSession":[]}],"description":"Administrator-only, same-origin policy and integrations:manage; UTF-8 JSON up to 8 KiB. Create/rotate returns a token exactly once. Rotation invalidates the old key immediately and keeps expiry. Every valid key can use all published reference content immediately; there is no separate per-source grant to manage. A 503 after mutation can mean the write committed: inspect metadata before retrying, especially create/rotate.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CredentialOperation"}}}},"responses":{"200":{"description":"Successful response","headers":{"X-Request-ID":{"description":"Support correlation identifier. Do not include credentials or patient data in support requests.","schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"},"example":"no-store"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CredentialOperationResult"}}}},"400":{"description":"Invalid request, query, audience assertion or identifier.","headers":{"X-Request-ID":{"description":"Support correlation identifier. Do not include credentials or patient data in support requests.","schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"},"example":"no-store"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, revoked or mismatched identity.","headers":{"X-Request-ID":{"description":"Support correlation identifier. Do not include credentials or patient data in support requests.","schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"},"example":"no-store"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Identity lacks permission, origin is not permitted, or administrator policy is not satisfied.","headers":{"X-Request-ID":{"description":"Support correlation identifier. Do not include credentials or patient data in support requests.","schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"},"example":"no-store"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Credential not found in the authorized organization.","headers":{"X-Request-ID":{"description":"Support correlation identifier. Do not include credentials or patient data in support requests.","schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"},"example":"no-store"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Inactive credential.","headers":{"X-Request-ID":{"description":"Support correlation identifier. Do not include credentials or patient data in support requests.","schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"},"example":"no-store"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request body exceeds the endpoint's size limit.","headers":{"X-Request-ID":{"description":"Support correlation identifier. Do not include credentials or patient data in support requests.","schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"},"example":"no-store"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Administrator request limit reached. Apply a bounded delayed retry.","headers":{"X-Request-ID":{"description":"Support correlation identifier. Do not include credentials or patient data in support requests.","schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"},"example":"no-store"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server failure. Use the request ID for support without sending credentials or query text.","headers":{"X-Request-ID":{"description":"Support correlation identifier. Do not include credentials or patient data in support requests.","schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"},"example":"no-store"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Reference service is unavailable. A lifecycle operation may already have committed: inspect administrator metadata before retrying.","headers":{"X-Request-ID":{"description":"Support correlation identifier. Do not include credentials or patient data in support requests.","schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"},"example":"no-store"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"machineBearer":{"type":"http","scheme":"bearer","bearerFormat":"awr_ + 43 base64url characters","description":"Opaque reference:retrieve key, stored only on the caller's server. No cookies or X-Organization-ID may accompany machine requests. Optional audience assertion headers must match the key. Each key is independently revocable, may have a finite expiry or explicitly never expire, and can use every published reference source immediately."},"adminSession":{"type":"http","scheme":"bearer","bearerFormat":"Supabase administrator access JWT","description":"Verified short-lived administrator JWT, subject to normal MFA, organization and integrations:manage checks. The first-party UI alternatively uses automatic Supabase SSR session cookies (dynamic project-specific cookie names and chunks). This scheme never accepts awr_ machine credentials."}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"requestId":{"type":"string"}}},"Status":{"type":"object","required":["contract","credential","capabilities","limits"],"properties":{"contract":{"const":"aimedis.wiki.reference.v1"},"credential":{"type":"object","required":["id","name","audience","scope","expiresAt"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"audience":{"type":"string","minLength":2,"maxLength":64,"pattern":"^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"},"scope":{"const":"reference:retrieve"},"expiresAt":{"type":["string","null"],"format":"date-time","description":"Credential expiry timestamp, or null for Never expires. On creation, supply a future expiry within 365 days or explicit null; omission is invalid. Listed finite credentials may already be expired. Rotation preserves this value, including null."}}},"capabilities":{"type":"object","required":["retrieve","sources","podcasts"],"properties":{"retrieve":{"const":true},"sources":{"const":true},"podcasts":{"const":true}}},"limits":{"type":"object","required":["requestsPerMinute","maxQueryCharacters","maxResults"],"properties":{"requestsPerMinute":{"const":30},"maxQueryCharacters":{"const":300},"maxResults":{"const":6}}}}},"Source":{"type":"object","required":["id","title","description","language","version","license","podcast"],"properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"description":{"type":"string"},"language":{"type":"string"},"version":{"type":"integer"},"license":{"type":"string"},"podcast":{"type":"boolean","description":"Reference source is tagged as a podcast and eligible for audio playback."}}},"SourceList":{"type":"object","required":["contract","sources","nextCursor"],"properties":{"contract":{"const":"aimedis.wiki.reference.v1"},"sources":{"type":"array","maxItems":50,"items":{"$ref":"#/components/schemas/Source"}},"nextCursor":{"type":["string","null"],"format":"uuid"}}},"RetrieveRequest":{"type":"object","additionalProperties":false,"required":["query"],"properties":{"query":{"type":"string","minLength":3,"maxLength":300,"description":"General reference topic only; server enforces UTF-16 length and rejects fewer than 3 trimmed characters."},"limit":{"type":"integer","minimum":1,"maximum":6,"default":6}}},"ReferenceHit":{"type":"object","required":["id","sourceId","title","content","score","version","license","corpus"],"properties":{"id":{"type":"string","format":"uuid"},"sourceId":{"type":"string","format":"uuid"},"title":{"type":"string","maxLength":1000},"content":{"type":"string","maxLength":4000},"score":{"type":"number","description":"Vector similarity, not a clinical evidence rating or calibrated probability."},"version":{"type":"integer"},"license":{"type":"string"},"corpus":{"const":"reference"},"page":{"type":"integer"},"startSeconds":{"type":"number"}}},"RetrieveResponse":{"type":"object","required":["contract","mode","insufficientEvidence","hits"],"properties":{"contract":{"const":"aimedis.wiki.reference.v1"},"mode":{"const":"vector"},"insufficientEvidence":{"type":"boolean","description":"True only when no hits were returned; false does not certify clinical sufficiency."},"hits":{"type":"array","maxItems":6,"items":{"$ref":"#/components/schemas/ReferenceHit"}}}},"Podcast":{"type":"object","required":["id","title","description","language","version","license","mimeType"],"properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"description":{"type":"string"},"language":{"type":"string"},"version":{"type":"integer"},"license":{"type":"string"},"mimeType":{"type":"string","enum":["audio/mpeg","audio/mp4","audio/wav","audio/x-wav","audio/ogg","audio/flac","audio/aac","audio/webm"]}}},"PodcastList":{"type":"object","required":["contract","podcasts"],"properties":{"contract":{"const":"aimedis.wiki.podcasts.v1"},"podcasts":{"type":"array","items":{"$ref":"#/components/schemas/Podcast"}}}},"Credential":{"type":"object","required":["id","name","audience","scope","createdAt","expiresAt","enabled"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"audience":{"type":"string","minLength":2,"maxLength":64,"pattern":"^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"},"scope":{"const":"reference:retrieve"},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":["string","null"],"format":"date-time","description":"Credential expiry timestamp, or null for Never expires. On creation, supply a future expiry within 365 days or explicit null; omission is invalid. Listed finite credentials may already be expired. Rotation preserves this value, including null."},"revokedAt":{"type":["string","null"],"format":"date-time"},"lastUsedAt":{"type":["string","null"],"format":"date-time"},"enabled":{"type":"boolean"}}},"CredentialList":{"type":"object","required":["credentials","consumers","truncated"],"properties":{"credentials":{"type":"array","maxItems":500,"items":{"$ref":"#/components/schemas/Credential"}},"consumers":{"type":"array","items":{"type":"string","minLength":2,"maxLength":64,"pattern":"^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"},"description":"Built-in audience suggestions; other valid custom audience slugs can be created."},"truncated":{"type":"object","required":["credentials"],"properties":{"credentials":{"type":"boolean"}}}}},"CredentialOperation":{"oneOf":[{"type":"object","additionalProperties":false,"required":["operation","name","expiresAt"],"properties":{"operation":{"const":"create","type":"string"},"name":{"type":"string","minLength":1,"maxLength":120},"audience":{"type":"string","minLength":2,"maxLength":64,"pattern":"^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$","default":"aimedis-care-pro"},"expiresAt":{"type":["string","null"],"format":"date-time","description":"Credential expiry timestamp, or null for Never expires. On creation, supply a future expiry within 365 days or explicit null; omission is invalid. Listed finite credentials may already be expired. Rotation preserves this value, including null."}}},{"type":"object","additionalProperties":false,"required":["operation","credentialId"],"properties":{"operation":{"const":"rotate","type":"string"},"credentialId":{"type":"string","format":"uuid"}}},{"type":"object","additionalProperties":false,"required":["operation","credentialId"],"properties":{"operation":{"const":"revoke","type":"string"},"credentialId":{"type":"string","format":"uuid"}}}],"discriminator":{"propertyName":"operation"}},"CredentialOperationResult":{"type":"object","required":["id","operation"],"properties":{"id":{"type":"string","format":"uuid"},"operation":{"type":"string","enum":["create","rotate","revoke"]},"token":{"type":"string","pattern":"^awr_[A-Za-z0-9_-]{43}$","description":"Returned once only on create/rotate. Store in protected server configuration and never log it."}}}}}}