Ingest a connection-scoped SDK-derived signal

Persists an SDK-derived signal under the APP tenant when the presented API key has signal:write scope and the SDK connection allows the requested signal type. Signal payloads are limited to JSON objects no larger than 64 KiB and are validated against the namespace's payload schema (shallow event shape — scalars, shallow arrays/objects of scalars; SDK_SIGNAL_PAYLOAD_SCHEMA_MISMATCH on violation). Payloads MUST NOT contain PHI: no identifiers (names, emails, phone numbers, MRNs, external patient ids), free-text clinical notes, diagnoses, or document content — the subject is identified by the connection, and clinical facts belong on the FHIR surfaces. Requests must include Idempotency-Key for safe retries.

POST/api/sdk/v1/signals

Authorization

platformApiKey

AuthorizationBearer <token>

CuraeAI Platform API key using the format Bearer . Keys are opaque credentials such as cae_live_..., not JWTs.

In: header

Header Parameters

Idempotency-Key*string

Required mutation idempotency key for SDK signal retries.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

connectionId*string

Public SDK connection id returned by POST /api/sdk/v1/connections.

signalType*

Structured (namespace, code, version) tuple identifying an SDK-derived signal. Replaces the pre-W1 flat AppDerivedSignalType enum (Docs/strategy/SDK_PRODUCT_FINDINGS.md § 3 W1) so adding a new clinical / wellness domain is a platform-side registry addition rather than a Prisma enum migration. Structurally a 1:1 projection of FHIR R4's Coding shape with simpler field names — the FHIR-canonical projection is {system: 'https://curaeai.com/fhir/CodeSystem/sdk-signal/<namespace>', code: <code>, version: <version>}. The simpler tuple is the developer-facing wire shape ("make it as easy as possible to develop medical apps", per the platform thesis); downstream FHIR servers and bulk exports project to the canonical form. Consumer-app attribution is not part of the type — the emitting customer-account is captured by the API key's principal context and surfaced through audit logs and webhook payloads. Two different sexual-health apps emitting the same {namespace: 'sti', code: 'exposure_event', version: 'v1'} are emitting the same semantic signal and resolve to the same platform sensitivity classification. Signals are for app-derived events with no EHR analog (exposure-notification dispatches, behavioural check-ins, self-asserted lifestyle facts). EHR-derivable questions ("does the user have a negative STI panel within 30 days?", "is the user up-to-date on CDC childhood vaccinations?") are queries against the resource-search surface, not signals — see searchSdkObservations / searchSdkConditions / searchSdkImmunizations.

payload*

observedAt?string

Response Body

`application/json`

`application/problem+json`

curl -X POST "https://example.com/api/sdk/v1/signals" \  -H "Idempotency-Key: string" \  -H "Content-Type: application/json" \  -d '{    "connectionId": "84b500d7-71c8-4b1f-adf4-f1eb0000973d",    "signalType": {      "namespace": "sti",      "code": "exposure_event",      "version": "v1"    },    "payload": {}  }'

{  "id": "string",  "signalType": {    "namespace": "sti",    "code": "exposure_event",    "version": "v1"  },  "sensitivity": "string",  "observedAt": "2019-08-24T14:15:22Z",  "createdAt": "2019-08-24T14:15:22Z"}

{  "type": "string",  "title": "string",  "status": 0,  "detail": "string",  "instance": "string",  "code": "string",  "details": {},  "retryable": true}