> For the complete documentation index, see [llms.txt](https://flapjax.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://flapjax.gitbook.io/docs/rest-api/reference/record-events/create-record.md).

# Create Record

## Create a record

> Creates a new record in the specified stack. The request body is a flat JSON object where each key corresponds to an attribute defined on the stack.\
> \
> Supported for both \*\*Item\*\* and \*\*Event\*\* stack types. Event records are immutable after creation — they cannot be updated, patched, or deleted via the API.\
> \
> Relationship attributes (Person-type and Stack-type) are automatically normalized: plain string values like \`"user-001"\` become \`{"external\_id": "user-001"}\`. Referenced entities that don't yet exist are auto-created to ensure relationship links are always valid.\
> \
> {% hint style="info" %}\
> String values are automatically trimmed of whitespace before processing.\
> {% endhint %}<br>

```json
{"openapi":"3.0.3","info":{"title":"Listener API","version":"1.0.0"},"tags":[{"name":"create-record"}],"servers":[{"url":"https://{domain}/v1","variables":{"domain":{"default":"your-domain","description":"Your deployment domain"}}}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"JWT token with the required scope for the endpoint. Pass via the `Authorization: Bearer <token>` header.\n"}},"parameters":{"StackKey":{"name":"stack_key","in":"path","required":true,"description":"The unique key identifying the stack.","schema":{"type":"string"}}},"schemas":{"RecordData":{"type":"object","description":"A flat JSON object of key-value pairs matching the stack's attribute definitions. Keys correspond to attribute keys configured on the stack. Relationship attributes accept plain values which are automatically normalized.\n","additionalProperties":true},"SuccessResponse":{"type":"object","description":"Standard success response envelope.","properties":{"status":{"type":"string","enum":["Success"]},"data":{"type":"boolean"}}},"ErrorResponse":{"type":"object","description":"Standard error response envelope.","properties":{"error":{"type":"string","description":"Machine-readable error type. Use this for programmatic error handling.\n","enum":["operation_failed","failed_binding_json","invalid_json","invalid_parameter","not_found","duplicate_entry","rate_limit_exceeded"]},"errorstack":{"type":"object","nullable":true,"description":"Detailed error stack (only present for server errors)."}}}}},"paths":{"/stacks/{stack_key}":{"post":{"summary":"Create a record","operationId":"createRecord","tags":["create-record"],"description":"Creates a new record in the specified stack. The request body is a flat JSON object where each key corresponds to an attribute defined on the stack.\n\nSupported for both **Item** and **Event** stack types. Event records are immutable after creation — they cannot be updated, patched, or deleted via the API.\n\nRelationship attributes (Person-type and Stack-type) are automatically normalized: plain string values like `\"user-001\"` become `{\"external_id\": \"user-001\"}`. Referenced entities that don't yet exist are auto-created to ensure relationship links are always valid.\n\n{% hint style=\"info\" %}\nString values are automatically trimmed of whitespace before processing.\n{% endhint %}\n","parameters":[{"$ref":"#/components/parameters/StackKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecordData"}}}},"responses":{"201":{"description":"Record created successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Invalid request body or unsupported stack type.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Stack not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```