---
name: getting-started
description: >-
  Authenticate with the xCures API and apply the rules every xCures call shares:
  the base URL, the ProjectId header, pagination, polling, retries, and the status
  codes to branch on. Use before any other xCures skill, or when a call fails and
  you need to decide whether to retry.
rbac:
  '*': read
tags:
  - basics
  - authentication
---

# Getting Started with the xCures API

## When to use

Use this skill first, before any workflow skill. It covers what every xCures call
shares. The workflow skills assume you already hold a token and a project ID.

## Steps

1. Get a token with `POST https://partner.xcures.com/oauth/token`. Send a JSON body
   with `client_id`, `client_secret`, and `grant_type` set to `client_credentials`.
   Read the credentials from environment variables or a secret store, never from
   the conversation. The response holds `access_token`. Tokens last 1 hour.
2. Send `Authorization: Bearer <access_token>` on every call. The base URL is
   `https://partner.xcures.com`.
3. List the projects your credentials can access with
   `GET /api/v1/patient-registry/project`. This call needs no `ProjectId` header.
   Ask the person you work for which project to use when there is more than one.
   Never choose a production project on your own.
4. Send `ProjectId: <project id>` on every other call.
5. Page through search results with `pageNumber` (starting at 1) and `pageSize`
   (default 50). Each page returns `results` and `totalCount`. Stop when
   `pageNumber * pageSize` reaches `totalCount`.
6. Poll long-running work instead of waiting on one call. Poll a query with
   `GET /api/v1/patient-registry/query/{id}` every 30 seconds until `ccdaStatus` is
   `completed`, `exhausted`, or `error`. Poll
   `GET /api/v1/patient-registry/subject/{id}/status/clinical-concepts` until
   `loaded` is `true` before you read Clinical Concepts or evaluate a checklist.
7. Keep 10 to 15 requests in flight at most. Retry `429`, `502`, `503`, and `504`
   with exponential backoff, and honor `Retry-After` when present.
8. Branch on the status code:
   - `400`: fix the request against the reference; do not retry it unchanged.
   - `401`: request a new token and retry once.
   - `403`: check the `ProjectId` header and the credential's permissions; do not retry.
   - `404`: check the ID in the path and the project in the header.
   - `409`: read the resource's current state before acting again.
   - `500`: stop and report it.

## Safety

- The API calls a patient a subject. You generate each subject `id` as a UUID, so a
  retried create targets the same record.
- Each `POST /api/v1/patient-registry/query` starts a new network request. Check
  `GET /api/v1/patient-registry/query?subjectId={id}` before you retry one.
- Print IDs and counts, not patient names, birth dates, or record content. Do not
  log or store signed document URLs.

## Reference

- Agent entry point with runnable examples: [https://docs.xcures.com/ai-agents.md](https://docs.xcures.com/ai-agents.md)
- xCures API reference: [https://docs.xcures.com/apis/current.md](https://docs.xcures.com/apis/current.md)