# Record a rapid point-of-care test result

Operation ID: `diagnostics.createRapidTest`

Create a rapid test Observation for a patient (COVID, flu, pregnancy, glucose, etc.). Returns the created test's test_id — use it with diagnostics.getScanUploadUrl to attach a photo of the test device, or with diagnostics.getTestResult to retrieve it later. administered_date is accepted as an alias for performed_date/performed_datetime; when none of the three date fields are supplied, the test is recorded as performed today. When encounter_id (or athena_encounter_id directly) is supplied and the tenant has Athena with this patient linked, the result is also mirrored to the Athena chart as a lab order + lab result document (image attached when scan_storage_key resolves to one) — a best-effort, non-fatal step reported back via athena_status/athena_error/athena_order_id; the FHIR write always succeeds independently of the Athena outcome.

## Public method

`createRapidTest`

Signature: `diagnostics.createRapidTest(patientId, request)`

Return type: `Promise<RapidTestResponse>`

## Authentication

Classification: **AUTHENTICATED**

Schemes: `bearerAuth`

## Prerequisites

None documented.

## HTTP

`POST /patients/{patient_id}/diagnostics/rapid-tests`

## Path parameters

| Name | Type | Required | Format | Allowed values | Default | Nullable | Description |
|---|---|---:|---|---|---|---:|---|
| `patient_id` | `string` | Yes |  |  |  | No |  |

## Query parameters

None.

## Body parameters

| Name | Type | Required | Format | Allowed values | Default | Nullable | Description |
|---|---|---:|---|---|---|---:|---|
| `body` | [`CreateRapidTestRequest`](../models/CreateRapidTestRequest.md) | No |  |  |  | No |  |

Request model: [`CreateRapidTestRequest`](../models/CreateRapidTestRequest.md)

## Request example

```json
{
  "administered_date": "string",
  "athena_encounter_id": "string",
  "device_name": "string",
  "encounter_id": "string",
  "lot_number": "string",
  "notes": "string",
  "performed_date": "2026-01-01",
  "performed_datetime": "2026-01-01T09:00:00Z",
  "quantitative_unit": "string",
  "quantitative_value": 0,
  "result": "positive",
  "scan_storage_key": "string",
  "specimen_type": "blood",
  "type": "covid19"
}
```

## Success responses

| Status | Shape | Content type | Description |
|---|---|---|---|
| `201` | [`CreateRapidTestResponse`](../models/CreateRapidTestResponse.md) | application/json | Rapid point-of-care test result created |

## Success response examples

### 201

```json
{
  "athena_error": "string",
  "athena_order_id": "string",
  "athena_status": "linked",
  "collected_by": "string",
  "derived_from": [
    "string"
  ],
  "device_name": "string",
  "encounter_id": "string",
  "fhir_id": "string",
  "lot_number": "string",
  "notes": "string",
  "performed_by": "string",
  "performed_date": "2026-01-01",
  "performed_datetime": "2026-01-01T09:00:00Z",
  "quantitative_unit": "string",
  "quantitative_value": 0,
  "result": "positive",
  "specimen_type": "nasopharyngeal_swab",
  "status": "final",
  "test_id": "00000000-0000-0000-0000-000000000000",
  "type": "covid19"
}
```

## Common errors

| Status | Shape | Content type | Description |
|---|---|---|---|
| `400` | [`diagnostics.ErrorResponse`](../models/diagnostics.ErrorResponse.md) | application/json | The request body was missing, or a field value was invalid |
| `401` | [`diagnostics.ErrorResponse`](../models/diagnostics.ErrorResponse.md) | application/json | Authorization required — missing or invalid Bearer JWT |
| `403` | [`diagnostics.ErrorResponse`](../models/diagnostics.ErrorResponse.md) | application/json | A PATIENT-pool caller attempted to access another patient's data |
| `404` | [`diagnostics.ErrorResponse`](../models/diagnostics.ErrorResponse.md) | application/json | The PATIENT-pool caller's own FHIR Patient record could not be resolved |
| `500` | [`diagnostics.ErrorResponse`](../models/diagnostics.ErrorResponse.md) | application/json | Internal server error |

## Error examples

### 400 — A field value failed validation (sanitized example)

```json
{
  "error": "'not-a-real-type' is not a valid RapidTestType"
}
```

### 400 — No request body was supplied

```json
{
  "error": "Request body is required"
}
```

### 401 — Missing or invalid access token

```json
{
  "error": "Authorization required"
}
```

### 403 — The caller's own FHIR patient id does not match patient_id

```json
{
  "error": "Cannot access another patient's data"
}
```

### 404 — The caller's own patient record was not found

```json
{
  "error": "Patient not found"
}
```

### 500 — Unexpected service failure (sanitized example)

```json
{
  "error": "Internal server error"
}
```

## NodeJS / TypeScript implementation

```ts
import { HCSDK } from "@healthcloudai/hc-sdk";
```

```ts
const patientId = "<PATIENT_ID>";

const request = {
  "administered_date": "string",
  "athena_encounter_id": "string",
  "device_name": "string",
  "encounter_id": "string",
  "lot_number": "string",
  "notes": "string",
  "performed_date": "2026-01-01",
  "performed_datetime": "2026-01-01T09:00:00Z",
  "quantitative_unit": "string",
  "quantitative_value": 0,
  "result": "positive",
  "scan_storage_key": "string",
  "specimen_type": "blood",
  "type": "covid19"
};

const result = await diagnostics.createRapidTest(patientId, request);
```

## cURL

```bash
curl -X POST \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{"administered_date":"string","athena_encounter_id":"string","device_name":"string","encounter_id":"string","lot_number":"string","notes":"string","performed_date":"2026-01-01","performed_datetime":"2026-01-01T09:00:00Z","quantitative_unit":"string","quantitative_value":0,"result":"positive","scan_storage_key":"string","specimen_type":"blood","type":"covid19"}' \
  'https://dev-api-diagnostics.health.cloud/patients/%3CPATIENT_ID%3E/diagnostics/rapid-tests'
```

## Notes

None.

## Prepared Test Console scenario

No canonical scenario is currently associated.

## Real response

No approved real integration response is currently published. Unapproved candidates are never rendered as examples.