Developer guides

Aimedis Wiki · Reference API

Connect your AI to reviewed Wiki evidence

The Wiki API is the Wiki's read-only, server-to-server REST API for Aimedis applications and approved external platforms and AI clients. Your application sends a general medical question and receives up to six cited excerpts from the Wiki's published, reviewed reference library, each with its title, version, licence and, where available, page. Your own AI model or feature uses them as evidence. The API generates no answers, never returns patient data or original files, and cannot change anything.

Request integration accessExplore Aimedis Wiki

From question to cited answer

  1. Get an API key

    A Wiki administrator creates a read-only reference API key for your application in the Wiki's Integrations screen. The key is bound to one application ID (an Aimedis application or a custom ID for your platform or AI) and expires after 1–365 days or never. The key (awr_…) is shown only once: store it in your server's protected configuration and send it as Authorization: Bearer <key>. Administrators can rotate or revoke it at any time. Do not send cookies, an administrator token or X-Organization-ID with it.

  2. Retrieve evidence

    Call POST /retrieve from your application server with a general topic, never patient details. Wiki returns up to six cited excerpts from its published, reviewed reference sources. Keep the key out of browsers, prompts, URLs and logs; legacy awk_ integration keys are disabled.

  3. Ground your answer

    Pass the excerpts to your model as untrusted evidence, never as instructions. Preserve citations and licences. If no relevant excerpt is returned, show that the evidence is insufficient. Similarity scores do not measure clinical certainty.

Two APIs: integrations use the Wiki API

The Wiki also has an internal administrator API for its own web app. Aimedis applications and third parties integrate through the Wiki API with an API key; administrator routes refuse API keys.

AspectWiki API (applications and third parties)Administrator API (internal)
Base pathhttps://wiki.aimedis.com/api/reference/v1https://wiki.aimedis.com/api/v1
AuthenticationAPI key: Authorization: Bearer awr_…Wiki administrator sign-in session; MFA applies to administrators who have enrolled it
Who uses itAimedis applications, external platforms and AI clientsThe Wiki's own web app and its administrators
Includesstatus, sources, retrieve and podcastsWorkspace, uploads, review, retrieve, ask and the MCP bridge
Third-party integrationsYes: this is the integration APINo: an API key is refused here (HTTP 403)

Get an API key

Keys come only from a Wiki administrator, who issues, rotates and revokes them in the Wiki's Integrations screen; there is no public self-service sign-up. Hosted retrieval with a key was verified live on 25 September 2026.

  • The administrator creates a key with a name, an application ID and an expiry of 1–365 days or Never expires.
  • Each key is bound to one application ID: one of the eight Aimedis applications listed below, or a custom ID for another platform or AI (2–64 lowercase letters, digits and single hyphens, starting with a letter).
  • The key is awr_ followed by 43 characters and is shown only once. Hand it over securely; it cannot be recovered later.
  • Rotation shows a new key once, stops the old key immediately and keeps the expiry. Revocation takes effect immediately. Every use is audit-logged.
  • Every valid key can read all published, reviewed reference sources of its organization, plus sources that other approved organizations share to the network. There are no per-source grants, so publishing a source makes it available to every key.
  • A key is read-only (scope reference:retrieve). It never gives access to patient data, uploads, publication, administration or original files.

Aimedis application IDs

  • aimedis-care-pro
  • aimedis-appointment
  • aimedis-connect
  • aimedis-onboarding
  • aimedis-pro-portal
  • aimedis-rehab
  • aimedis-wiki
  • aimedis-decision-pro

Endpoints

Every endpoint requires the API key, except the public OpenAPI contract. Responses of the keyed endpoints carry an X-Request-ID header and Cache-Control: private, no-store.

Base URLhttps://wiki.aimedis.com/api/reference/v1
GET /status
RequestNo parameters.
ResponseKey metadata, capabilities and limits. Call it first to confirm the key.
GET /sources
RequestOptional limit from 1 to 50 (default 25) and the cursor from the previous page.
ResponseMetadata of published sources, paged. Pass nextCursor unchanged into the next request until it is null.
POST /retrieve
RequestJSON body with query and an optional limit.
ResponseUp to six cited excerpts.
GET /podcasts
RequestNo parameters.
ResponsePublished, reviewed podcasts with licence and audio format.
GET /podcasts/{id}/audio
RequestPodcast ID and an optional single Range header, for example bytes=0-65535.
ResponseAudio streamed through the Wiki (200 or 206); storage URLs are never disclosed. Multiple ranges are rejected (416).
GET /openapi.json
RequestPublic; no key needed.
ResponseThe OpenAPI 3.1 contract.
OpenAPI 3.1 contract · public, no key needed

The machine-readable contract of the Wiki API. The administrator API has a separate schema that requires administrator sign-in.

Retrieve reference passages

These examples run on your application server with your own reference API key (awr_…), read from protected server configuration such as WIKI_REFERENCE_TOKEN. Never put the key in a browser, mobile app, prompt, URL or log. Send general knowledge questions without patient identifiers or copied patient records.

POSThttps://wiki.aimedis.com/api/reference/v1/retrieve

cURL · confirm the key with GET /status

curl --fail-with-body --max-time 30 \
  'https://wiki.aimedis.com/api/reference/v1/status' \
  --header "Authorization: Bearer $WIKI_REFERENCE_TOKEN"

cURL · retrieve excerpts

curl --fail-with-body --max-time 30 \
  --request POST 'https://wiki.aimedis.com/api/reference/v1/retrieve' \
  --header "Authorization: Bearer $WIKI_REFERENCE_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"query":"Evidence appraisal methods","limit":6}'

Examples only: set WIKI_REFERENCE_TOKEN to your awr_ API key in protected server configuration. No request runs on this page.

Request contract

FieldContract
AuthorizationRequired. Authorization: Bearer awr_… (awr_ followed by 43 base64url characters), issued once by a Wiki administrator; read-only scope reference:retrieve. An optional X-Wiki-Application header must equal the key's application ID. Requests that also carry cookies or X-Organization-ID are rejected with 401.
queryRequired string of 3–300 characters (at least 3 after trimming). General topics only: queries with obvious e-mail addresses, web addresses, UUIDs, long phone or ID numbers, dates or API-key strings are rejected with HTTP 400. Numeric ranges such as 6.5-7.0 count as dates, so describe ranges in words.
limitOptional integer from 1 to 6; default 6. Fewer hits, or none, can be returned.

The request body accepts only query and an optional limit; corpus, tenant, patient or any other field is rejected with HTTP 400. Results always come from the reference corpus; patient data is never available through the API. The JSON body is limited to 16 KiB.

Keep the evidence and its provenance

The response contains contract: "aimedis.wiki.reference.v1", mode: "vector", insufficientEvidence and hits (at most six). insufficientEvidence is true only when no hits are returned; false does not mean the evidence is clinically sufficient. Each hit provides the following fields; optional locators appear only when available.

id · sourceId
Excerpt and source identifiers for traceable citations.
title · content
Source title and the retrieved excerpt, at most 4,000 characters.
version · license
Source version and the source's licence.
score · corpus
Vector similarity, not a clinical confidence, and the corpus, which is always reference.
page? · startSeconds?
Optional page number or audio/video timestamp. The API returns no source URL, original file or storage link.

How retrieval works

  • Questions are embedded with Voyage AI (voyage-3-large) and matched by vector similarity against the published reference library. Passages below a minimum similarity of 0.55 are not returned.
  • Queries are sent to the embedding provider, Voyage AI. Send general topics only. The identifier check catches only obvious patterns; it is a safety net, not de-identification. Never send patient data.
  • The server takes up to 60 nearest candidates, leaves out non-content passages (a guideline's reference list, table of contents, abbreviation list or a near-empty page) and exact duplicates, then returns the best excerpts up to limit, in similarity order. A response can therefore contain fewer hits than limit, or none. Nothing is deleted from the library.
  • insufficientEvidence: true means no hits were returned (HTTP 200, not an error). false does not mean the evidence answers the question; your application decides.
  • Every hit carries its source's licence, and sources without a licence are never returned. Licences differ: many guidelines are CC BY, CC BY-SA or CC0, others are NonCommercial (CC BY-NC, CC BY-NC-SA, CC BY-NC-ND), and some reserve all rights, in some cases including AI and text-and-data-mining use. Check the licence of each hit before you show, store or reuse the excerpt, attribute the source, and do not use a NonCommercial excerpt commercially.
  • Excerpts can change when sources are revised or retired. Responses carry Cache-Control: private, no-store; if your application caches results, keep the cache brief.

Limits and errors

Each API key may make 30 requests per minute, and the reference service accepts 120 requests per minute across all keys; status, sources, podcast and audio calls count too. HTTP 429 includes Retry-After: 60. The JSON request body is limited to 16 KiB. The API is for server-to-server calls: it sends no CORS headers, so browsers cannot read its responses, and POST /retrieve rejects a foreign Origin header with HTTP 403.

An empty hits array is a valid insufficient-evidence result, not an error. Error responses contain an error message; unexpected server errors (500) also contain a requestId. 401 responses carry WWW-Authenticate. For support, report the X-Request-ID header or the requestId, never the key or the query.

400 / 413
An invalid field or length, an unknown field, an identifier-like query or a body over 16 KiB. Fix the request before retrying.
401
The API key is missing, malformed, expired, revoked or replaced by rotation; the request also carried cookies, an administrator token or X-Organization-ID; or X-Wiki-Application does not match the key. Ask your Wiki administrator for a valid key.
403
The route or origin is not allowed: the key was used on an administrator route, or POST /retrieve arrived with a foreign Origin header, as a browser request would. Call the Wiki API paths from a server. Respect the denial; never switch to a more privileged credential.
404 / 416
404: the podcast is not available to this key. 416: the Range header is malformed or lists more than one range; send one range within the file's length.
429
A per-key or service-wide rate limit was reached. Wait the Retry-After seconds, then retry with backoff and less concurrency.
500 / 503
500: an unexpected error, which includes an embedding-provider error or timeout; retry once with backoff, then report the requestId. 503: the embedding configuration or the database is temporarily unavailable; retry later with bounded backoff.

Implementation steps

  1. Ask the Wiki administrator for a key for your application ID.
  2. Store it on your server only, for example in the environment variable WIKI_REFERENCE_TOKEN. Never put it in a browser, mobile app, prompt, URL or log.
  3. Call GET /status to confirm the key.
  4. For each user question, derive a general topic without names, dates, IDs or patient details, and call POST /retrieve.
  5. Give the excerpts to your model as numbered, untrusted evidence, never as instructions, and require citations. Show title, version, page and licence to your users. Abstain, or say that there is not enough evidence, when no relevant hits are returned.
  6. Handle 429, 503 and transient 500 errors with bounded retries. Cache results only briefly, because excerpts can change when sources are revised or retired.
  7. Before go-live, test status, retrieval with provenance, an expired or revoked key (401), rotation, rate limiting and outage handling.

TypeScript · application server

export async function retrieveWikiEvidence(query: string) {
  const response = await fetch(
    "https://wiki.aimedis.com/api/reference/v1/retrieve",
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.WIKI_REFERENCE_TOKEN}`,
        "Content-Type": "application/json",
        Accept: "application/json",
      },
      body: JSON.stringify({ query, limit: 6 }),
      signal: AbortSignal.timeout(30_000),
      redirect: "error",
      cache: "no-store",
    },
  );
  if (!response.ok) {
    throw new Error(`HTTP ${response.status}`);
  }
  return response.json();
}

Python · application server

import json, os, urllib.request

def retrieve_wiki_evidence(query: str, limit: int = 6) -> dict:
    request = urllib.request.Request(
        "https://wiki.aimedis.com/api/reference/v1/retrieve",
        data=json.dumps({"query": query, "limit": limit}).encode("utf-8"),
        headers={
            "Authorization": f"Bearer {os.environ['WIKI_REFERENCE_TOKEN']}",
            "Content-Type": "application/json",
        },
        method="POST",
    )
    with urllib.request.urlopen(request, timeout=30) as response:
        return json.load(response)

Any HTTP client can call the API from the public OpenAPI contract. The Wiki team can provide TypeScript and Python sample clients for status, sources, retrieve, podcasts and audio; they are not published packages.

What the Wiki API does not do

  • It generates no answers: bring your own model. There is no AVA chat for third parties.
  • It returns no original documents, PDFs, files or download links.
  • It never returns patient data and performs no writes, uploads, reviews or administration.
  • It offers no MCP endpoint for third parties; the MCP bridge belongs to the administrator API.
  • It has no per-source permissions: a key reads all published reference sources of its organization.
  • It has no public self-service sign-up: keys come from a Wiki administrator.

Administrator API: not for integrations

The Wiki's own web app uses the administrator API at /api/v1. It requires an administrator sign-in with organization checks, and MFA for administrators who have enrolled it, and refuses API keys with HTTP 403. Use it only as a Wiki administrator; integrations use the Wiki API above.

Let Wiki generate the answer

POST /api/v1/ask

POST /api/v1/ask (administrator session only) returns a plain-text answer from the Wiki's server-selected Anthropic model. For reference questions it searches the Wiki library, PubMed and public health websites (MedlinePlus) in parallel. Its citations can therefore include PubMed abstracts and web pages that are not reviewed Wiki sources. Each citation carries its stage (wiki, pubmed or web) and, for PubMed and web evidence, a url. Use retrieve when your application supplies the model or needs reviewed Wiki evidence only.

MCP bridge for administrators

POST /api/v1/mcp

The administrator-authenticated, stateless JSON-RPC bridge supports initialize, notifications/initialized, tools/list and tools/call. Its knowledge_search and source_get tools exclude patient records. OAuth discovery and SSE transport are not supplied, and API keys cannot use it.

The administrator API schema requires administrator sign-in. The TypeScript SDK for the administrator API is repository source, not a published npm package; it works only with an administrator session, because the administrator routes refuse API keys.

Ask a Wiki administrator for an API key. Before go-live, test the integration with general, fictional questions: status, provenance, an expired or revoked key, rotation, rate limiting and outage handling.

Request integration access