> ## Documentation Index > Fetch the complete documentation index at: https://docs.arlohealth.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create Care Job > Propose a real-world care action that Arlo's care team executes after the user approves: `move_referral` (an EXTERNAL referral written by an outside provider), `book_appointment`, or `cancel_or_reschedule`. Returns `status: pending_approval` and an `approvalUrl`. Hand the URL to the user and never open it yourself: approval requires the user's own verification on their device. Links expire after 15 minutes. Then poll GET /api/care-jobs/{id} until approved, declined, or expired. Wherever the action points at a provider's office, pass BOTH identity (`npi` from the pricing routes, or `providerName`) and location (`city` + `state`, plus `facilityName` / `address` / `phone` when known). Pass `patientId` (from GET /api/profile) for a dependent. Records release, refills, claim disputes, and standing payment grants are not available yet (`JOB_TYPE_NOT_AVAILABLE`). Send an `Idempotency-Key` header on retries so a lost response never creates a second job. ## OpenAPI ````yaml api-reference/openapi.yaml POST /api/care-jobs openapi: 3.1.0 info: title: Arlo Health MCP Server version: 1.0.0 description: | Healthcare infrastructure for AI agents. Everything an agent needs to act in healthcare for its user. ## Overview This server exposes two interfaces: - **MCP** (Model Context Protocol) over streamable HTTP at `/` for AI agents - **REST API** at `/api/*` for bots, skills, and direct HTTP clients Both interfaces use the same tool handlers and authentication. ## Authentication OAuth 2.1 with PKCE. All `/api/*` endpoints require a Bearer token. Discovery endpoints (no auth required): - `/.well-known/oauth-protected-resource` - `/.well-known/oauth-authorization-server` - `/.well-known/mcp.json` (MCP Server Card) ## Service Regions Care is licensed by where the patient is physically located when they request it, so every conversation carries an ISO 3166-2 `region` code. Arlo currently serves California, United States (`US-CA`); an unsupported region is refused with `REGION_NOT_SUPPORTED`, whose payload names the regions Arlo serves at that moment. contact: name: Arlo Health url: https://arlohealth.ai license: name: Proprietary url: https://arlohealth.ai/tos servers: - url: https://mcp.arlohealth.ai description: Production MCP Server security: - oauth2: - openid - profile - email - offline_access tags: - name: Discovery description: MCP and OAuth discovery endpoints (no auth required) - name: Profile description: User profile and patient information - name: Consultations description: Healthcare consultation management - name: Messaging description: Conversation messaging and media - name: Prescriptions description: Prescription orders (read-only; Photon Health fulfills them) - name: Health Records description: The user's connected insurance and health records (US) - name: Care Pricing description: Free price transparency under the user's plan (US) - name: Care Jobs description: >- Real-world care actions Arlo's care team executes after the patient approves (US) - name: Payment description: Billing and pay-per-use payment management - name: Webhooks description: Webhook registration and status paths: /api/care-jobs: post: tags: - Care Jobs summary: Submit a care job description: | Propose a real-world care action that Arlo's care team executes after the user approves: `move_referral` (an EXTERNAL referral written by an outside provider), `book_appointment`, or `cancel_or_reschedule`. Returns `status: pending_approval` and an `approvalUrl`. Hand the URL to the user and never open it yourself: approval requires the user's own verification on their device. Links expire after 15 minutes. Then poll GET /api/care-jobs/{id} until approved, declined, or expired. Wherever the action points at a provider's office, pass BOTH identity (`npi` from the pricing routes, or `providerName`) and location (`city` + `state`, plus `facilityName` / `address` / `phone` when known). Pass `patientId` (from GET /api/profile) for a dependent. Records release, refills, claim disputes, and standing payment grants are not available yet (`JOB_TYPE_NOT_AVAILABLE`). Send an `Idempotency-Key` header on retries so a lost response never creates a second job. operationId: createCareJob parameters: - name: Idempotency-Key in: header required: false schema: type: string description: >- Reuse the same key when retrying this exact create; the original result is replayed instead of creating a second job requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CareJobInput' responses: '200': description: Request created, awaiting the user's approval content: application/json: schema: $ref: '#/components/schemas/CareJobCreated' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' components: schemas: CareJobInput: type: object required: - jobType properties: jobType: type: string enum: - move_referral - book_appointment - cancel_or_reschedule patientId: type: string description: >- Which patient on the account this is for (from GET /api/profile). Omit for the default patient. params: type: object description: | Action-specific fields. move_referral: specialty, referral {description (required), writtenApprox?, referenceNumber?}, source {providerName?, facilityName?, phone?}, target {npi | providerName, city, state, facilityName?, address?, phone?}, optional appointmentLabel, estimates, savingsCents, openings. book_appointment: provider {npi | providerName, city, state, ...}, specialty?, appointmentLabel?, reason?, estimates?. cancel_or_reschedule: appointmentLabel, provider {...}, newTimeLabel?. context: type: string description: >- Short plain-language reason, shown on the approval sheet attributed as the agent's note cost: type: object description: >- Only for cost-bearing actions. The sheet collects a manual-capture hold; capture happens on completion. properties: amountCents: type: integer description: type: string idempotencyKey: type: string description: Alternative to the Idempotency-Key header CareJobCreated: type: object properties: status: type: string enum: - pending_approval jobId: type: string jobType: type: string tier: type: string description: Approval tier, assigned server-side approvalUrl: type: string format: uri description: >- Hand to the user. Never open it yourself. Expires 15 minutes after creation. expiresAt: type: - integer - string sheet: type: object description: What the user will see on the approval sheet agentInstructions: type: array items: type: string Error: type: object description: Error response properties: error: type: string description: Error code reason: type: string description: Human-readable explanation code: type: string description: Detailed error code responses: BadRequest: description: Invalid request content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: Missing or invalid authentication content: application/json: schema: type: object properties: error: type: string needsAuth: type: boolean securitySchemes: oauth2: type: oauth2 description: OAuth 2.1 with PKCE flows: authorizationCode: authorizationUrl: /oauth/authorize tokenUrl: /oauth/token scopes: openid: OpenID Connect profile: User profile email: Email address offline_access: Refresh tokens ````