{"templateId":"./@theme/Templates/IntroPage","sharedDataIds":{},"props":{"metadata":{"markdoc":{"tagList":["intro-hero","section-header","step"]},"type":"markdown"},"seo":{"title":"AI Agents | xCures API Hub","description":"Use the xCures API with AI agents. Discovery files, authentication, safe call order, pagination, polling, retries, and status codes.","siteUrl":"https://docs.xcures.com","llmstxt":{"details":{"content":"Start with the AI agents page. It covers the base URL, authentication, the ProjectId header, the safe call order, pagination, polling, retries, and the status codes to branch on. The API calls a patient a subject. The agent skills index is at https://docs.xcures.com/.well-known/agent-skills/index.json."},"sections":[{"title":"Start here","includeFiles":["ai-agents.md"]},{"title":"API reference","includeFiles":["apis/current.json"]}]},"jsonLd":{"@context":"https://schema.org","@type":"Organization","name":"xCures","legalName":"xCures, Inc.","url":"https://www.xcures.com","logo":"https://docs.xcures.com/images/xCures-2026.svg","description":"xCures retrieves, organizes, and structures medical records and presents encounter specific checklists and summaries so care teams can act with confidence."}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"XcIntroHero","attributes":{"eyebrow":"AI Agents","title":"Use the xCures® API with AI agents","description":"This page is the starting point for AI agents and for the developers who direct them. It collects the rules an agent needs to call the xCures API safely, in one place."},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Last reviewed: October 28, 2026."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Version: checked against API version ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["V1"]},", the version the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://docs.xcures.com/_bundle/apis/current.yaml"},"children":["OpenAPI description"]}," states. The ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/changelog"},"children":["changelog"]}," records each change to this page."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every rule here comes from the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/current"},"children":["API reference"]},", the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/changelog"},"children":["changelog"]},", or another page on this site."," ","When this page and the API reference disagree, the API reference wins."]},{"$$mdtype":"Tag","name":"XcSectionHeader","attributes":{"title":"Give your agent these sources","icon":"IconChainLink1"},"children":[]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Source"},"children":["Source"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"URL"},"children":["URL"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"What it holds"},"children":["What it holds"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["This page as Markdown"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://docs.xcures.com/ai-agents.md"},"children":["https://docs.xcures.com/ai-agents.md"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The rules on this page, as plain Markdown."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["llms.txt"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://docs.xcures.com/llms.txt"},"children":["https://docs.xcures.com/llms.txt"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["An index for language models that lists this page and the API reference."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["API reference index"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://docs.xcures.com/apis/current.md"},"children":["https://docs.xcures.com/apis/current.md"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Every endpoint, with a Markdown link per operation."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["OpenAPI description"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://docs.xcures.com/_bundle/apis/current.yaml"},"children":["https://docs.xcures.com/_bundle/apis/current.yaml"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The full machine-readable API description."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Agent skills"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://docs.xcures.com/.well-known/agent-skills/index.json"},"children":["https://docs.xcures.com/.well-known/agent-skills/index.json"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Step-by-step workflow guides in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SKILL.md"]}," format."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Changelog"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://docs.xcures.com/changelog"},"children":["https://docs.xcures.com/changelog"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["API changes by date, including new endpoints, removed fields, planned deprecations, and changes to this page."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The SDKs, FAQ, Platform User Guide, and Data Dictionary pages require a portal sign-in."," ","An agent without a sign-in sees only the public pages, the API reference, and the agent skills."," ","This page restates the facts from those pages that an agent needs most."]},{"$$mdtype":"Tag","name":"XcSectionHeader","attributes":{"title":"Ground rules for agents","icon":"IconShield2"},"children":[]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Read the reference before every call."]}," Use the exact path, method, headers, and required fields. Never guess an endpoint or a field name."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Keep secrets out of the conversation."]}," Read ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_id"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_secret"]}," from environment variables or a secret store. Never paste them into a prompt, a log, or a file in a repository."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Start in a non-production project."]}," Non-production projects do not connect to live networks and should not hold real patient data. Use the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api-introduction#de-identified-demo-patients-for-testing"},"children":["de-identified demo patients"]}," to explore retrieved data."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Keep patient data out of prompts and logs."]}," Print IDs and counts, not names, birth dates, or record content. Do not log or store signed document URLs."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Ask before you write."]}," Reads are safe to repeat. Creating subjects, dispatching queries, and publishing documents change state, and a query reaches real health information networks in production."]}]},{"$$mdtype":"Tag","name":"XcSectionHeader","attributes":{"title":"Terms","icon":"IconBook"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The API uses one name for each concept. Use these names in code and in prompts."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Term"},"children":["Term"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Meaning"},"children":["Meaning"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Subject"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The API's name for a patient record. Pages say \"patient\" in prose; paths and fields say ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["subject"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["subjectId"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Project"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A workspace that holds subjects and their data. Almost every call sends the project's ID in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ProjectId"]}," header."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Organization"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Your xCures customer account. It holds one or more production projects and a sandbox project, plus any other test projects. Not the same as the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["organizationIds"]}," list on Create Query, which names a health-network organization."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Query"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["One records request for one subject across connected health information networks. Its progress is in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ccdaStatus"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Document"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A record retrieved for a subject or uploaded for one. Downloads and uploads use short-lived signed URLs."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Clinical Concepts"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Structured data xCures extracts from a subject's documents, one endpoint per concept type."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Checklist"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A set of questions xCures answers from a subject's records, with supporting evidence."]}]}]}]}]},{"$$mdtype":"Tag","name":"XcSectionHeader","attributes":{"title":"Base URL and authentication","icon":"IconLock"},"children":[]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Item"},"children":["Item"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Value"},"children":["Value"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Base URL"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://partner.xcures.com"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Token URL"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST https://partner.xcures.com/oauth/token"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Grant type"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_credentials"]},", sent as a JSON body"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Token response"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["access_token"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["token_type"]},", which is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Bearer"]},". No ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["expires_in"]}," field is returned."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Token lifetime"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["1 hour. Request a new token when a call returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Headers on every call"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorization: Bearer <access_token>"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Project header"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ProjectId: <project UUID>"]}," on every call except Get Token and List Projects"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Create API credentials in the portal, as the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api-introduction#api-credential-management"},"children":["API Introduction"]}," shows."," ","Each credential is scoped to production or non-production projects, never both."]},{"$$mdtype":"Tag","name":"XcSectionHeader","attributes":{"title":"The safe call order","icon":"IconNumberedList"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The examples use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["curl"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["jq"]},"."," ","Set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["XCURES_CLIENT_ID"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["XCURES_CLIENT_SECRET"]}," in your shell from your secret store first."," ","Run the blocks in order, in one shell session: each block uses the variables the blocks before it set."]},{"$$mdtype":"Tag","name":"XcStep","attributes":{"id":"get-a-token","step":1,"title":"Get a token","icon":"IconTicket"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"XCURES_BASE_URL=\"https://partner.xcures.com\"\n\nXCURES_TOKEN=\"$(curl -sS --fail-with-body -X POST \"$XCURES_BASE_URL/oauth/token\" \\\n  -H 'content-type: application/json' \\\n  -d \"$(jq -n --arg id \"$XCURES_CLIENT_ID\" --arg secret \"$XCURES_CLIENT_SECRET\" \\\n        '{client_id: $id, client_secret: $secret, grant_type: \"client_credentials\"}')\" \\\n  | jq -r '.access_token')\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Treat any ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["2xx"]}," status as success, and check that ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["access_token"]}," is present."," ","The response holds two fields:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"access_token\": \"<access token>\",\n  \"token_type\": \"Bearer\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The response has no ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["expires_in"]}," field, so track the 1-hour lifetime yourself or request a new token when a call returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/current/oauth/publicoauthcontroller_token"},"children":["Get Token reference"]}," documents a JSON body (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["application/json"]},"), and the JSON call above is the one to use."," ","The endpoint also accepts the standard OAuth form-encoded body (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["application/x-www-form-urlencoded"]},") with the same three fields, but the reference does not document it."]},{"$$mdtype":"Tag","name":"XcStep","attributes":{"id":"list-your-projects","step":2,"title":"List your projects","icon":"IconMagnifyingGlass"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["List Projects is the one data call that needs no ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ProjectId"]}," header."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -sS --fail-with-body \"$XCURES_BASE_URL/api/v1/patient-registry/project\" \\\n  -H \"authorization: Bearer $XCURES_TOKEN\" \\\n  | jq '.[] | {id, name}'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Ask the person you work for which project to use, by name, and set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["XCURES_PROJECT_NAME"]}," to it."," ","Never pick a production project on your own."," ","This block sets ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["XCURES_PROJECT_ID"]}," from that name:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"XCURES_PROJECT_ID=\"$(curl -sS --fail-with-body \"$XCURES_BASE_URL/api/v1/patient-registry/project\" \\\n  -H \"authorization: Bearer $XCURES_TOKEN\" \\\n  | jq -r --arg name \"$XCURES_PROJECT_NAME\" '.[] | select(.name == $name) | .id')\"\necho \"ProjectId: $XCURES_PROJECT_ID\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"XcStep","attributes":{"id":"read-before-you-write","step":3,"title":"Read before you write","icon":"IconSearchMenu"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Search Subjects is read-only. This call prints the total and the first page of subject IDs."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -sS --fail-with-body -G \"$XCURES_BASE_URL/api/v1/patient-registry/subject\" \\\n  --data-urlencode \"pageNumber=1\" \\\n  --data-urlencode \"pageSize=10\" \\\n  -H \"authorization: Bearer $XCURES_TOKEN\" \\\n  -H \"ProjectId: $XCURES_PROJECT_ID\" \\\n  | jq '{totalCount, subjectIds: [.results[].id]}'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"XcStep","attributes":{"id":"create-a-subject","step":4,"title":"Create a subject","icon":"IconUserAdd"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You generate the subject ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," yourself, as a UUID."," ","Only ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["firstName"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["lastName"]}," are required, but more demographics improve ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api-introduction#best-practices-for-patient-matching"},"children":["patient matching"]},"."," ","The example uses synthetic values."," ","By default, creating a subject also dispatches its first query."," ","The example sets ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["options.initiateEhrQuery"]}," to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["false"]},", so the call creates only the subject and the query becomes its own step that you ask about first."," ","The flag defaults to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]}," when you omit it."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"SUBJECT_ID=\"$(uuidgen | tr '[:upper:]' '[:lower:]')\"\n\ncurl -sS --fail-with-body -X POST \"$XCURES_BASE_URL/api/v2/patient-registry/subject\" \\\n  -H \"authorization: Bearer $XCURES_TOKEN\" \\\n  -H \"ProjectId: $XCURES_PROJECT_ID\" \\\n  -H 'content-type: application/json' \\\n  -d \"$(jq -n --arg id \"$SUBJECT_ID\" '{\n        id: $id,\n        firstName: \"Avery\",\n        lastName: \"Synthetic\",\n        birthDate: \"1980-01-15\",\n        gender: \"F\",\n        addressPostalCode: \"55401\",\n        options: { initiateEhrQuery: false }\n      }')\" \\\n  | jq '{id, identifier}'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To create many subjects, use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /api/v1/patient-registry/subject"]}," with at most 10 subjects per request."," ","To turn off the queries for a whole batch, send ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{\"subjects\": [...], \"options\": {\"initiateEhrQueries\": false}}"]},"."," ","That flag is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["initiateEhrQueries"]},", plural, and it also defaults to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]},"."," ","The ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://docs.xcures.com/.well-known/agent-skills/bulk-patient-onboarding/SKILL.md"},"children":["bulk onboarding skill"]}," covers that path."]},{"$$mdtype":"Tag","name":"XcStep","attributes":{"id":"dispatch-a-query","step":5,"title":"Dispatch a query","icon":"IconPaperPlane"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A query reaches real health information networks in production."," ","Ask the person you work for before you run this block."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"QUERY_ID=\"$(curl -sS --fail-with-body -X POST \"$XCURES_BASE_URL/api/v1/patient-registry/query\" \\\n  -H \"authorization: Bearer $XCURES_TOKEN\" \\\n  -H \"ProjectId: $XCURES_PROJECT_ID\" \\\n  -H 'content-type: application/json' \\\n  -d \"$(jq -n --arg id \"$SUBJECT_ID\" '{subjectId: $id}')\" \\\n  | jq -r '.id')\"\necho \"QueryId: $QUERY_ID\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every call to Create Query starts a new records request."," ","Before you retry a failed call, check whether a query already exists."," ","If you created the subject without turning the flag off, its query already exists, so read its ID instead of dispatching a second one:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"QUERY_ID=\"$(curl -sS --fail-with-body -G \"$XCURES_BASE_URL/api/v1/patient-registry/query\" \\\n  --data-urlencode \"subjectId=$SUBJECT_ID\" \\\n  -H \"authorization: Bearer $XCURES_TOKEN\" \\\n  -H \"ProjectId: $XCURES_PROJECT_ID\" \\\n  | jq -r '.results[0].id')\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To refresh records later, dispatch a new query the same way, after you ask."]},{"$$mdtype":"Tag","name":"XcStep","attributes":{"id":"poll-until-the-query-finishes","step":6,"title":"Poll until the query finishes","icon":"IconRotate"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"while :; do\n  status=\"$(curl -sS --fail-with-body \"$XCURES_BASE_URL/api/v1/patient-registry/query/$QUERY_ID\" \\\n    -H \"authorization: Bearer $XCURES_TOKEN\" \\\n    -H \"ProjectId: $XCURES_PROJECT_ID\" \\\n    | jq -r '.ccdaStatus')\"\n  echo \"ccdaStatus: $status\"\n  case \"$status\" in completed|exhausted|error) break ;; esac\n  sleep 30\ndone\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A production query usually takes 20 to 30 minutes."," ","The API documents no maximum wait for a query."," ","Agree on a time budget with the person you work for before you start."," ","When it runs out, stop polling, report the query ID and its last ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ccdaStatus"]},", and resume later from the stored ID."," ","Request a new token if the loop runs past the token's 1-hour lifetime."]},{"$$mdtype":"Tag","name":"XcStep","attributes":{"id":"read-the-results","step":7,"title":"Read the results","icon":"IconFileText"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["List the subject's documents:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -sS --fail-with-body -G \"$XCURES_BASE_URL/api/v1/patient-registry/document\" \\\n  --data-urlencode \"subjectId=$SUBJECT_ID\" \\\n  -H \"authorization: Bearer $XCURES_TOKEN\" \\\n  -H \"ProjectId: $XCURES_PROJECT_ID\" \\\n  | jq '{totalCount, documentIds: [.results[].id]}'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Check that Clinical Concepts are ready, then read one concept type:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -sS --fail-with-body \"$XCURES_BASE_URL/api/v1/patient-registry/subject/$SUBJECT_ID/status/clinical-concepts\" \\\n  -H \"authorization: Bearer $XCURES_TOKEN\" \\\n  -H \"ProjectId: $XCURES_PROJECT_ID\" \\\n  | jq '.loaded'\n\ncurl -sS --fail-with-body -G \"$XCURES_BASE_URL/api/v1/patient-registry/clinical-concepts/condition\" \\\n  --data-urlencode \"subjectId=$SUBJECT_ID\" \\\n  -H \"authorization: Bearer $XCURES_TOKEN\" \\\n  -H \"ProjectId: $XCURES_PROJECT_ID\" \\\n  | jq '{totalCount}'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"XcSectionHeader","attributes":{"title":"Long-running work","icon":"IconClock"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Nothing in the API blocks while records are retrieved or processed."," ","A create call answers at once with the new record, and you poll for progress."," ","The API reference documents no ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["202 Accepted"]}," responses."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Work"},"children":["Work"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"How to wait"},"children":["How to wait"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Stop when"},"children":["Stop when"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Query"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Poll ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /api/v1/patient-registry/query/{id}"]}," every 30 seconds."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ccdaStatus"]}," is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["completed"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["exhausted"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Clinical Concepts processing"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Poll ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /api/v1/patient-registry/subject/{id}/status/clinical-concepts"]},"."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["loaded"]}," is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Checklist evaluation"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Poll Clinical Concepts status first. Evaluating before ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["loaded"]}," is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]}," returns empty or partial results."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["loaded"]}," is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]},"; then evaluate."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["None of these waits has a documented maximum."," ","Agree on a time budget with the person you work for before you start."," ","When the budget runs out, stop, report the query or subject ID and its last status, and resume later."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The other ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ccdaStatus"]}," values are ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["delayed"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["initiated"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pending"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["inProgress"]},", and mean the query is still running."," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["exhausted"]}," is one of the seven ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ccdaStatus"]}," values in the API reference, which gives it no further description."," ","Treat it as finished, like ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["completed"]},": stop polling, then wait for Clinical Concepts as you would after ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["completed"]},"."," ","Read the subject's documents to see what the query retrieved before you decide, with the person you work for, whether to query again."," ","When a query ends in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error"]},", ask before you dispatch one fresh query and poll it."," ","If that query also ends in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error"]},", stop and report both query IDs."," ","Store query IDs as you create them, so an interrupted polling pass can resume."]},{"$$mdtype":"Tag","name":"XcSectionHeader","attributes":{"title":"Checklist operations","icon":"IconChecklist"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The API has four checklist operations."," ","Each one takes the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ProjectId"]}," header."]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/current/checklist/publicchecklistcontroller_list"},"children":["Get Checklists"]}," lists the project's checklists. Read-only."," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /api/v1/patient-registry/checklist"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/current/checklist/publicchecklistcontroller_get"},"children":["Get Checklist"]}," returns one checklist with each item's questions. Read-only."," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /api/v1/patient-registry/checklist/{checklistId}"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/current/checklist/publicchecklistcontroller_evaluate"},"children":["Evaluate Checklist"]}," evaluates a checklist for one subject and returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["201"]},". The body takes ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["subjectId"]},", required, and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["regenerate"]},", optional."," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /api/v1/patient-registry/checklist/{checklistId}/evaluate"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/current/checklist/publicchecklistcontroller_submititemfeedback"},"children":["Submit Checklist Item Feedback"]}," records feedback on one item. It changes state, so ask first."," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /api/v1/patient-registry/checklist/{checklistId}/item/{checklistItemId}/feedback"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Evaluate a checklist only after Clinical Concepts ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["loaded"]}," is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]},"."," ","The ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/changelog#october-27-2026"},"children":["October 27, 2026 changelog"]}," says an evaluation answers the item definition version it was evaluated with; when that differs from the version the checklist now uses, read the checklist again."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/changelog#october-23-2026"},"children":["October 23, 2026 changelog"]}," removed two response fields: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["eligibilitySatisfied"]}," from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ChecklistEvaluationResult"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["meetsCriteria"]}," from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ChecklistItemEvaluationResult"]},"."," ","Both fields are no longer returned, so do not read them."]},{"$$mdtype":"Tag","name":"XcSectionHeader","attributes":{"title":"Pagination","icon":"IconListBullets"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Search endpoints take ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pageNumber"]}," (starting at 1, default 1) and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pageSize"]}," (default 50)."," ","Each page returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["results"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["totalCount"]},"."," ","The API reference documents no maximum ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pageSize"]},", so use the default of 50 and page until you have ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["totalCount"]}," results."," ","The FHIR resource endpoints require both ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pageNumber"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pageSize"]},"."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"page=1\nsize=50\nwhile :; do\n  resp=\"$(curl -sS --fail-with-body -G \"$XCURES_BASE_URL/api/v1/patient-registry/subject\" \\\n    --data-urlencode \"pageNumber=$page\" \\\n    --data-urlencode \"pageSize=$size\" \\\n    -H \"authorization: Bearer $XCURES_TOKEN\" \\\n    -H \"ProjectId: $XCURES_PROJECT_ID\")\"\n  echo \"$resp\" | jq -r '.results[].id'\n  total=\"$(echo \"$resp\" | jq -r '.totalCount')\"\n  [ $((page * size)) -ge \"$total\" ] && break\n  page=$((page + 1))\ndone\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"XcSectionHeader","attributes":{"title":"Rate limits, retries, and repeated calls","icon":"IconGauge"},"children":[]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Concurrency."]}," Keep at most 10 requests in flight, the ceiling the xCures SDKs use. Beyond that, expect ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["429"]}," responses."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Rate limits."]}," Limits adapt to load and are not published. Traffic near the limit is slowed, so rising latency is the first sign."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Backoff."]}," Retry ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["429"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["502"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["503"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["504"]}," with exponential backoff and jitter. Honor a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Retry-After"]}," header when the response has one. The xCures SDKs do both."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Retry count."]}," The API documents no retry limit. Set a fixed cap on retries per call before you start, as the SDKs do with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["maxAttempts"]},". When a call reaches the cap, stop and report the call, its last status code, and the IDs involved."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["No idempotency keys."]}," The API documents no idempotency header, so make retries safe yourself."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Subjects."]}," You choose each subject ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]},", so a retried create targets the same record. If a retry returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["409"]},", read the subject with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /api/v1/patient-registry/subject/{id}"]}," before you do anything else."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Queries."]}," Each Create Query call starts a new network request. Check for an existing query before you retry."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Checklists."]}," Re-running an evaluation is safe. Set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["regenerate"]}," to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]}," to force a fresh evaluation."]}]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Limit"},"children":["Limit"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Value"},"children":["Value"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"When you reach it"},"children":["When you reach it"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Requests in flight"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["10"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Wait for a request to finish before you send the next one."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Retries per call"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No documented limit"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Stop at your own cap and report."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Subjects per create request"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["10"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Split the roster into batches of 10."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pageSize"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No documented limit. The default is 50."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Use 50 and request the next page."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Query wait"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No documented limit. A production query usually takes 20 to 30 minutes."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Stop at the agreed time budget, report the query ID and last ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ccdaStatus"]},", and resume later."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Clinical Concepts and checklist wait"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No documented limit"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Stop at the agreed time budget, report the subject ID, and resume later."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Fresh queries after ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No documented limit"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Ask before one fresh query. If it also ends in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error"]},", stop and report both query IDs."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Token lifetime"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["1 hour"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Request a new token."]}]}]}]}]},{"$$mdtype":"Tag","name":"XcSectionHeader","attributes":{"title":"Status codes to branch on","icon":"IconExclamationTriangle"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Where the API reference documents an error body, it is JSON with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["title"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["detail"]}," fields."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Code"},"children":["Code"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Meaning"},"children":["Meaning"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"What the agent does"},"children":["What the agent does"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["200"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["201"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Success."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Continue."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The request is invalid, often a missing or malformed field."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Fix the request against the reference. Do not retry it unchanged."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The bearer token is missing, invalid, or expired."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Request a new token and retry once."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["403"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Authenticated but not allowed."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Check the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ProjectId"]}," header and the credential's projects and permissions. Some features, such as Summary and Reciprocity, must be enabled on the project. Do not retry."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["404"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The resource was not found."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Check the ID in the path and the project in the header."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["409"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The request conflicts with the current state of a resource."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Read the resource's current state before you act again."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["429"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Too many requests."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Back off, lower concurrency, then retry."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["500"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["An error on the xCures side."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Stop and report it. Contact xCures support if it persists."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["503"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The service is unavailable."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Retry with backoff. Check ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://status.xcures.com/"},"children":["status.xcures.com"]},"."]}]}]}]}]},{"$$mdtype":"Tag","name":"XcSectionHeader","attributes":{"title":"Pick a workflow","icon":"IconChip"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://docs.xcures.com/.well-known/agent-skills/index.json"},"children":["agent skill"]}," lists the calls for one workflow, in order."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Goal"},"children":["Goal"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Skill"},"children":["Skill"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Diagram"},"children":["Diagram"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Learn the shared rules: auth, headers, paging, polling, errors"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://docs.xcures.com/.well-known/agent-skills/getting-started/SKILL.md"},"children":["getting-started"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["This page"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Register a new patient and retrieve their records"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://docs.xcures.com/.well-known/agent-skills/standard-treatment-workflow/SKILL.md"},"children":["standard-treatment-workflow"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api-introduction#standard-treatment-workflow"},"children":["Standard Treatment Workflow"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Upload records you already hold"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://docs.xcures.com/.well-known/agent-skills/byod-ingestion/SKILL.md"},"children":["byod-ingestion"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api-introduction#bring-your-own-data-byod-workflow"},"children":["BYOD Workflow"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Retrieve raw documents with no xCures processing"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://docs.xcures.com/.well-known/agent-skills/retrieval-only/SKILL.md"},"children":["retrieval-only"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api-introduction#retrieval-only-workflow"},"children":["Retrieval Only Workflow"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Refresh records for a patient already registered"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://docs.xcures.com/.well-known/agent-skills/requery-patient/SKILL.md"},"children":["requery-patient"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api-introduction#existing-patient-requery-workflow"},"children":["Existing Patient / Requery Workflow"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Register and query a large roster"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://docs.xcures.com/.well-known/agent-skills/bulk-patient-onboarding/SKILL.md"},"children":["bulk-patient-onboarding"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api-introduction#bulk-patient-onboarding"},"children":["Bulk Patient Onboarding"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Publish a document back to the network"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://docs.xcures.com/.well-known/agent-skills/reciprocity/SKILL.md"},"children":["reciprocity"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api-introduction#reciprocity-workflow"},"children":["Reciprocity Workflow"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"XcSectionHeader","attributes":{"title":"Clinical Concepts types","icon":"IconBrain"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each type has a search endpoint at ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /api/v1/patient-registry/clinical-concepts/{type}"]}," and a get-by-ID endpoint at ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /api/v1/patient-registry/clinical-concepts/{type}/{id}"]},"."," ","Both require the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["subjectId"]}," query parameter."," ","The 16 types use these exact path segments:"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["allergy"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["biomarker"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["care_team"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["condition"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["coverage"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["demographic"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["encounter"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["family_history"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["imaging"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["lab"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["medication"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["procedure"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["radiation"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["social_history"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["survey"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["vital"]}]},{"$$mdtype":"Tag","name":"XcSectionHeader","attributes":{"title":"Report a problem with these docs","icon":"IconHeadphones"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To report a wrong or incomplete page, email ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"mailto:help@xcures.com"},"children":["help@xcures.com"]}," or use the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/support"},"children":["Support"]}," page."]}]},"headings":[],"frontmatter":{"seo":{"title":"AI Agents | xCures API Hub","description":"Use the xCures API with AI agents. Discovery files, authentication, safe call order, pagination, polling, retries, and status codes."},"template":"./@theme/Templates/IntroPage","toc":[{"label":"Give your agent these sources","href":"#give-your-agent-these-sources","icon":"IconChainLink1"},{"label":"Ground rules for agents","href":"#ground-rules-for-agents","icon":"IconShield2"},{"label":"Terms","href":"#terms","icon":"IconBook"},{"label":"Base URL and authentication","href":"#base-url-and-authentication","icon":"IconLock"},{"label":"The safe call order","href":"#the-safe-call-order","icon":"IconNumberedList","children":[{"label":"Get a token","href":"#get-a-token","icon":"IconTicket"},{"label":"List your projects","href":"#list-your-projects","icon":"IconMagnifyingGlass"},{"label":"Read before you write","href":"#read-before-you-write","icon":"IconSearchMenu"},{"label":"Create a subject","href":"#create-a-subject","icon":"IconUserAdd"},{"label":"Dispatch a query","href":"#dispatch-a-query","icon":"IconPaperPlane"},{"label":"Poll until the query finishes","href":"#poll-until-the-query-finishes","icon":"IconRotate"},{"label":"Read the results","href":"#read-the-results","icon":"IconFileText"}]},{"label":"Long-running work","href":"#long-running-work","icon":"IconClock"},{"label":"Checklist operations","href":"#checklist-operations","icon":"IconChecklist"},{"label":"Pagination","href":"#pagination","icon":"IconListBullets"},{"label":"Rate limits, retries, and repeated calls","href":"#rate-limits-retries-and-repeated-calls","icon":"IconGauge"},{"label":"Status codes to branch on","href":"#status-codes-to-branch-on","icon":"IconExclamationTriangle"},{"label":"Pick a workflow","href":"#pick-a-workflow","icon":"IconChip"},{"label":"Clinical Concepts types","href":"#clinical-concepts-types","icon":"IconBrain"},{"label":"Report a problem with these docs","href":"#report-a-problem-with-these-docs","icon":"IconHeadphones"}]},"lastModified":"2026-11-01T14:52:28.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/ai-agents","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}