Upsert a record (hosted RecordStore.upsert)

curl -X POST https://api.runtype.com/v1/runtime/records/upsert \
     -H "Authorization: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "metadata": {},
  "name": "UserPreferences",
  "type": "settings"
}'

{
  "created": true,
  "record": {
    "createdAt": "2024-06-01T12:00:00Z",
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "metadata": {},
    "name": "UserPreferences",
    "organizationId": "org_987654321",
    "type": "settings",
    "updatedAt": "2024-06-01T12:00:00Z",
    "userId": "user_123456789",
    "messages": [
      {
        "content": "Record upserted successfully.",
        "role": "system"
      }
    ],
    "metadataLabels": {},
    "metadataSchema": {},
    "productSurfaceId": "prod_surface_123",
    "schemaValid": true
  }
}

Hosted fulfillment of the runtime RecordStore seam. Inserts or merges / replaces a record keyed by the authenticated caller’s ownership (org|user, type, name). Requires an Enterprise plan: ineligible accounts receive 403 (code BYOC_PLAN_REQUIRED).

Authentication

AuthorizationBearer

API key or Clerk session token

Request

This endpoint expects an object.

metadatamap from strings to anyRequired

namestringRequired>=1 character

typestringRequired>=1 character

mergeStrategyenumOptional

Allowed values:

Response

The stored record + created flag (dates as ISO-8601 strings)

createdboolean

recordobject

Errors

400

Bad Request Error

401

Unauthorized Error

402

Payment Required Error

403

Forbidden Error

404

Not Found Error

429

Too Many Requests Error

500

Internal Server Error