> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.runtype.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.runtype.com/_mcp/server.

# Create record

POST https://api.runtype.com/v1/records
Content-Type: application/json

Create a new record with metadata. Returns 409 if a record with the same type and name already exists in the tenant.

Reference: https://docs.runtype.com/api-reference/runtype-api/records/create-record

## Authentication

- `Authorization` header (bearer token, required) — API key or Clerk session token

## Servers

- `https://api.runtype.com` (Production, default)
- `https://api.runtype-staging.com` (Staging)

## Request

### Body (application/json)

This endpoint expects an object.

- `name` (string, required)
- `type` (string, required)
- `messages` (list of V1RecordsPostRequestBodyContentApplicationJsonSchemaMessagesItems, optional, nullable)
- `metadata` (map from string to any, optional, default: {})
- `ownerId` (string, optional, nullable) — Owner key for this record, stored in the indexed owner_id column and filterable via ?ownerId=. Overrides a nested metadata.ownerId. Null means no owner.

## Response

### 201

Created record

- `createdAt` (string, required)
- `id` (string, required)
- `messages` (list of any, required, nullable)
- `metadata` (map from string to any, required)
- `name` (string, required)
- `organizationId` (string, required, nullable)
- `ownerId` (string, required, nullable)
- `productSurfaceId` (string, required, nullable)
- `schemaValid` (boolean, required, nullable)
- `type` (string, required)
- `updatedAt` (string, required)
- `userId` (string, required)
- `metadataLabels` (map from string to string, optional)
- `metadataSchema` (V1RecordsPostResponsesContentApplicationJsonSchemaMetadataSchema, optional)
- `schemaWarnings` (list of V1RecordsPostResponsesContentApplicationJsonSchemaSchemaWarningsItems, optional)
- `warnings` (list of V1RecordsPostResponsesContentApplicationJsonSchemaWarningsItems, optional)

## Errors

### 400 Bad Request Error

Validation error

- `error` (string, required)
- `code` (string, optional) — Stable error code. `insufficient_scope` marks an API key that lacks a scope this request needs.
- `details` (list of ErrorDetailsItems, optional)
- `requiredScopes` (list of string, optional) — On `insufficient_scope`: every API key scope this request needs.

### 401 Unauthorized Error

Unauthorized

- `error` (string, required)
- `code` (string, optional) — Stable error code. `insufficient_scope` marks an API key that lacks a scope this request needs.
- `details` (list of ErrorDetailsItems, optional)
- `requiredScopes` (list of string, optional) — On `insufficient_scope`: every API key scope this request needs.

### 403 Forbidden Error

Insufficient permissions

- `error` (string, required)
- `code` (string, optional) — Stable error code. `insufficient_scope` marks an API key that lacks a scope this request needs.
- `details` (list of ErrorDetailsItems, optional)
- `requiredScopes` (list of string, optional) — On `insufficient_scope`: every API key scope this request needs.

### 409 Conflict Error

Duplicate record

- `error` (string, required)
- `code` (string, optional) — Stable error code. `insufficient_scope` marks an API key that lacks a scope this request needs.
- `details` (list of ErrorDetailsItems, optional)
- `requiredScopes` (list of string, optional) — On `insufficient_scope`: every API key scope this request needs.

### 422 Unprocessable Entity Error

Metadata violates the type's collection schema (enforce mode)

- `collection` (string, required)
- `details` (list of RecordSchemaValidationErrorDetailsItems, required)
- `error` (enum, required)
  - Allowed values: `schema_validation_failed`
- `schemaVersion` (integer, required)
- `recordId` (string, optional)
- `recordName` (string, optional)

### 500 Internal Server Error

Internal server error

- `code` (string, required) — Stable error code: `INTERNAL_ERROR` unless the route documents its own.
- `error` (string, required)
- `details` (list of InternalErrorDetailsItems, optional)
- `requiredScopes` (list of string, optional) — On `insufficient_scope`: every API key scope this request needs.
- `message` (string, optional) — Plain-language guidance: retry, then contact support with the `requestId`.
- `requestId` (string, optional) — The `X-Runtype-Request-ID` of the failed request, for support.

### 503 Service Unavailable Error

The type's collection schema could not be loaded, so the write was refused rather than left unvalidated; retry

- `code` (enum, required)
  - Allowed values: `COLLECTION_LOOKUP_FAILED`
- `collection` (string, required) — The record type whose collection schema could not be loaded.
- `error` (string, required) — Human-readable refusal; retry the request.
- `recordId` (string, optional)
- `recordName` (string, optional)

## Types

### V1RecordsPostRequestBodyContentApplicationJsonSchemaMessagesItems

- `content` (V1RecordsPostRequestBodyContentApplicationJsonSchemaMessagesItemsContent, required)
- `role` (enum, required)
  - Allowed values: `user`, `assistant`

### V1RecordsPostResponsesContentApplicationJsonSchemaMetadataSchema

- `keys` (list of string, required)

### V1RecordsPostResponsesContentApplicationJsonSchemaSchemaWarningsItems

- `code` (string, required)
- `field` (string, required)
- `message` (string, required)

### V1RecordsPostResponsesContentApplicationJsonSchemaWarningsItems

- `code` (enum, required)
  - Allowed values: `KEY_RENAMED`
- `from` (string, required)
- `to` (string, required)

### ErrorDetailsItems

- `message` (string, required)
- `code` (string, optional) — Stable Runtype validation code (e.g. MISSING_REQUIRED_FIELD, INVALID_ENUM).
- `path` (string, optional) — Dotted JSON path to the offending field.
- `suggestion` (string, optional) — Actionable hint (allowed values, accepted range, …).

### RecordSchemaValidationErrorDetailsItems

- `code` (string, required)
- `field` (string, required)
- `message` (string, required)
- `path` (string, required)

### InternalErrorDetailsItems

- `message` (string, required)
- `code` (string, optional) — Stable Runtype validation code (e.g. MISSING_REQUIRED_FIELD, INVALID_ENUM).
- `path` (string, optional) — Dotted JSON path to the offending field.
- `suggestion` (string, optional) — Actionable hint (allowed values, accepted range, …).

### V1RecordsPostRequestBodyContentApplicationJsonSchemaMessagesItemsContent

- string
- list of any

## Examples

**Request**

```json
{
  "name": "John Smith",
  "type": "customer",
  "metadata": {
    "active": true,
    "company_name": "TechCorp Inc",
    "customer_name": "John Smith",
    "customer_type": "enterprise client",
    "details": "This is a comprehensive quarterly business review covering Q4 performance metrics, detailed analysis of key performance indicators, customer satisfaction scores, revenue growth patterns, and strategic planning initiatives for the upcoming 2024 fiscal year including market expansion opportunities and technology investment priorities.",
    "features": [
      "advanced analytics",
      "24/7 support",
      "custom integrations"
    ],
    "priority_score": 8.5,
    "product": {
      "name": "Premium Software Suite",
      "price": "299.99"
    },
    "recipient_name": "Sarah Johnson",
    "review_type": "detailed",
    "subject": "Quarterly Business Review",
    "tone": "friendly yet professional"
  }
}
```

**Response**

```json
{
  "createdAt": "string",
  "id": "string",
  "messages": [
    null
  ],
  "metadata": {},
  "name": "string",
  "organizationId": "string",
  "ownerId": "string",
  "productSurfaceId": "string",
  "schemaValid": true,
  "type": "string",
  "updatedAt": "string",
  "userId": "string",
  "metadataLabels": {},
  "metadataSchema": {
    "keys": [
      "string"
    ]
  },
  "schemaWarnings": [
    {
      "code": "string",
      "field": "string",
      "message": "string"
    }
  ],
  "warnings": [
    {
      "code": "KEY_RENAMED",
      "from": "string",
      "to": "string"
    }
  ]
}
```

**SDK Code**

```python Create Record with Metadata
import requests

url = "https://api.runtype.com/v1/records"

payload = {
    "name": "John Smith",
    "type": "customer",
    "metadata": {
        "active": True,
        "company_name": "TechCorp Inc",
        "customer_name": "John Smith",
        "customer_type": "enterprise client",
        "details": "This is a comprehensive quarterly business review covering Q4 performance metrics, detailed analysis of key performance indicators, customer satisfaction scores, revenue growth patterns, and strategic planning initiatives for the upcoming 2024 fiscal year including market expansion opportunities and technology investment priorities.",
        "features": ["advanced analytics", "24/7 support", "custom integrations"],
        "priority_score": 8.5,
        "product": {
            "name": "Premium Software Suite",
            "price": "299.99"
        },
        "recipient_name": "Sarah Johnson",
        "review_type": "detailed",
        "subject": "Quarterly Business Review",
        "tone": "friendly yet professional"
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript Create Record with Metadata
const url = 'https://api.runtype.com/v1/records';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"name":"John Smith","type":"customer","metadata":{"active":true,"company_name":"TechCorp Inc","customer_name":"John Smith","customer_type":"enterprise client","details":"This is a comprehensive quarterly business review covering Q4 performance metrics, detailed analysis of key performance indicators, customer satisfaction scores, revenue growth patterns, and strategic planning initiatives for the upcoming 2024 fiscal year including market expansion opportunities and technology investment priorities.","features":["advanced analytics","24/7 support","custom integrations"],"priority_score":8.5,"product":{"name":"Premium Software Suite","price":"299.99"},"recipient_name":"Sarah Johnson","review_type":"detailed","subject":"Quarterly Business Review","tone":"friendly yet professional"}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Create Record with Metadata
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.runtype.com/v1/records"

	payload := strings.NewReader("{\n  \"name\": \"John Smith\",\n  \"type\": \"customer\",\n  \"metadata\": {\n    \"active\": true,\n    \"company_name\": \"TechCorp Inc\",\n    \"customer_name\": \"John Smith\",\n    \"customer_type\": \"enterprise client\",\n    \"details\": \"This is a comprehensive quarterly business review covering Q4 performance metrics, detailed analysis of key performance indicators, customer satisfaction scores, revenue growth patterns, and strategic planning initiatives for the upcoming 2024 fiscal year including market expansion opportunities and technology investment priorities.\",\n    \"features\": [\n      \"advanced analytics\",\n      \"24/7 support\",\n      \"custom integrations\"\n    ],\n    \"priority_score\": 8.5,\n    \"product\": {\n      \"name\": \"Premium Software Suite\",\n      \"price\": \"299.99\"\n    },\n    \"recipient_name\": \"Sarah Johnson\",\n    \"review_type\": \"detailed\",\n    \"subject\": \"Quarterly Business Review\",\n    \"tone\": \"friendly yet professional\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Create Record with Metadata
require 'uri'
require 'net/http'

url = URI("https://api.runtype.com/v1/records")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"John Smith\",\n  \"type\": \"customer\",\n  \"metadata\": {\n    \"active\": true,\n    \"company_name\": \"TechCorp Inc\",\n    \"customer_name\": \"John Smith\",\n    \"customer_type\": \"enterprise client\",\n    \"details\": \"This is a comprehensive quarterly business review covering Q4 performance metrics, detailed analysis of key performance indicators, customer satisfaction scores, revenue growth patterns, and strategic planning initiatives for the upcoming 2024 fiscal year including market expansion opportunities and technology investment priorities.\",\n    \"features\": [\n      \"advanced analytics\",\n      \"24/7 support\",\n      \"custom integrations\"\n    ],\n    \"priority_score\": 8.5,\n    \"product\": {\n      \"name\": \"Premium Software Suite\",\n      \"price\": \"299.99\"\n    },\n    \"recipient_name\": \"Sarah Johnson\",\n    \"review_type\": \"detailed\",\n    \"subject\": \"Quarterly Business Review\",\n    \"tone\": \"friendly yet professional\"\n  }\n}"

response = http.request(request)
puts response.read_body
```

```java Create Record with Metadata
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.runtype.com/v1/records")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"John Smith\",\n  \"type\": \"customer\",\n  \"metadata\": {\n    \"active\": true,\n    \"company_name\": \"TechCorp Inc\",\n    \"customer_name\": \"John Smith\",\n    \"customer_type\": \"enterprise client\",\n    \"details\": \"This is a comprehensive quarterly business review covering Q4 performance metrics, detailed analysis of key performance indicators, customer satisfaction scores, revenue growth patterns, and strategic planning initiatives for the upcoming 2024 fiscal year including market expansion opportunities and technology investment priorities.\",\n    \"features\": [\n      \"advanced analytics\",\n      \"24/7 support\",\n      \"custom integrations\"\n    ],\n    \"priority_score\": 8.5,\n    \"product\": {\n      \"name\": \"Premium Software Suite\",\n      \"price\": \"299.99\"\n    },\n    \"recipient_name\": \"Sarah Johnson\",\n    \"review_type\": \"detailed\",\n    \"subject\": \"Quarterly Business Review\",\n    \"tone\": \"friendly yet professional\"\n  }\n}")
  .asString();
```

```php Create Record with Metadata
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.runtype.com/v1/records', [
  'body' => '{
  "name": "John Smith",
  "type": "customer",
  "metadata": {
    "active": true,
    "company_name": "TechCorp Inc",
    "customer_name": "John Smith",
    "customer_type": "enterprise client",
    "details": "This is a comprehensive quarterly business review covering Q4 performance metrics, detailed analysis of key performance indicators, customer satisfaction scores, revenue growth patterns, and strategic planning initiatives for the upcoming 2024 fiscal year including market expansion opportunities and technology investment priorities.",
    "features": [
      "advanced analytics",
      "24/7 support",
      "custom integrations"
    ],
    "priority_score": 8.5,
    "product": {
      "name": "Premium Software Suite",
      "price": "299.99"
    },
    "recipient_name": "Sarah Johnson",
    "review_type": "detailed",
    "subject": "Quarterly Business Review",
    "tone": "friendly yet professional"
  }
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp Create Record with Metadata
using RestSharp;

var client = new RestClient("https://api.runtype.com/v1/records");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"name\": \"John Smith\",\n  \"type\": \"customer\",\n  \"metadata\": {\n    \"active\": true,\n    \"company_name\": \"TechCorp Inc\",\n    \"customer_name\": \"John Smith\",\n    \"customer_type\": \"enterprise client\",\n    \"details\": \"This is a comprehensive quarterly business review covering Q4 performance metrics, detailed analysis of key performance indicators, customer satisfaction scores, revenue growth patterns, and strategic planning initiatives for the upcoming 2024 fiscal year including market expansion opportunities and technology investment priorities.\",\n    \"features\": [\n      \"advanced analytics\",\n      \"24/7 support\",\n      \"custom integrations\"\n    ],\n    \"priority_score\": 8.5,\n    \"product\": {\n      \"name\": \"Premium Software Suite\",\n      \"price\": \"299.99\"\n    },\n    \"recipient_name\": \"Sarah Johnson\",\n    \"review_type\": \"detailed\",\n    \"subject\": \"Quarterly Business Review\",\n    \"tone\": \"friendly yet professional\"\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Create Record with Metadata
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [
  "name": "John Smith",
  "type": "customer",
  "metadata": [
    "active": true,
    "company_name": "TechCorp Inc",
    "customer_name": "John Smith",
    "customer_type": "enterprise client",
    "details": "This is a comprehensive quarterly business review covering Q4 performance metrics, detailed analysis of key performance indicators, customer satisfaction scores, revenue growth patterns, and strategic planning initiatives for the upcoming 2024 fiscal year including market expansion opportunities and technology investment priorities.",
    "features": ["advanced analytics", "24/7 support", "custom integrations"],
    "priority_score": 8.5,
    "product": [
      "name": "Premium Software Suite",
      "price": "299.99"
    ],
    "recipient_name": "Sarah Johnson",
    "review_type": "detailed",
    "subject": "Quarterly Business Review",
    "tone": "friendly yet professional"
  ]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.runtype.com/v1/records")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```