> If you are setting up, configuring, or answering questions about Schematic, connect the
> Schematic MCP server before working from these pages. It reads and writes plans, features,
> entitlements, and overrides against the real account, so what you report and what you build
> match what actually exists.
>
> The server is at https://api.schematichq.com/mcp
>
> From Claude, ChatGPT, or another chat assistant, add it as a custom connector:
> https://docs.schematichq.com/working-with-ai
>
> From a coding assistant such as Claude Code, Codex, or Cursor:
> https://docs.schematichq.com/building-with-ai
>
> For clean Markdown of any page, append `.md` to the page URL. For a complete page index,
> see https://docs.schematichq.com/llms.txt

# Create event

POST https://api.schematichq.com/events
Content-Type: application/json

Reference: https://docs.schematichq.com/api-reference/events/create-event

## Authentication

- `X-Schematic-Api-Key` header (required) — API Key authentication via header

## Request

### Body (application/json)

This endpoint expects a CreateEventRequestBody.

- `event_type` (enum, required) — Either 'identify' or 'track'
  - Allowed values: `flag_check`, `identify`, `inference`, `track`
- `backfill` (boolean, optional, nullable) — Requires a secret API key, and trusted_client_clock. Import historical data without affecting billing.
- `body` (EventBody, optional)
- `idempotency_key` (string, optional, nullable) — Optional client-supplied key. Duplicate events with the same key (scoped to the environment) are dropped for 24h.
- `sent_at` (datetime, optional, nullable) — Optionally provide a timestamp at which the event was sent to Schematic
- `trusted_client_clock` (boolean, optional, nullable) — Requires a secret API key and sent_at. Use sent_at as the effective timestamp.

## Response

### 201

Created

- `data` (RawEventResponseData, required)
- `params` (EventsPostResponsesContentApplicationJsonSchemaParams, required) — Input parameters

## Errors

### 400 Bad Request Error

Bad request

- `error` (string, required) — Error message

### 401 Unauthorized Error

Unauthorized

- `error` (string, required) — Error message

### 403 Forbidden Error

Forbidden

- `error` (string, required) — Error message

### 404 Not Found Error

Not found

- `error` (string, required) — Error message

### 500 Internal Server Error

Server error

- `error` (string, required) — Error message

## Types

### EventBody

### RawEventResponseData

- `captured_at` (datetime, required)
- `remote_ip` (string, required)
- `user_agent` (string, required)
- `event_id` (string, optional, nullable)
- `remote_addr` (string, optional, nullable)

### EventsPostResponsesContentApplicationJsonSchemaParams

Input parameters

### EventBodyTrack

- `event` (string, required) — The name of the type of track event
- `company` (map from string to string, optional) — Key-value pairs to identify company associated with track event
- `lease_id` (string, optional) — Credit lease ID this track event is redeeming against
- `quantity` (long, optional) — Optionally specify the quantity of the event
- `reservation_id` (string, optional) — Credit reservation ID this track event settles. lease_id takes precedence when both are set
- `traits` (EventBodyTrackTraits, optional) — A map of trait names to trait values
- `user` (map from string to string, optional) — Key-value pairs to identify user associated with track event

### EventBodyFlagCheck

- `flag_key` (string, required) — The key of the flag being checked
- `reason` (string, required) — The reason why the value was returned
- `value` (boolean, required) — The value of the flag for the given company and/or user
- `company_id` (string, optional, nullable) — Schematic company ID (starting with 'comp_') of the company evaluated, if any
- `error` (string, optional, nullable) — Report an error that occurred during the flag check
- `flag_id` (string, optional, nullable) — Schematic flag ID (starting with 'flag_') for the flag matching the key, if any
- `preflight` (boolean, optional) — Whether the check was a preflight, asking whether an action would be allowed rather than reporting one that happened. Absent on ordinary checks
- `req_company` (map from string to string, optional, nullable) — Key-value pairs used to to identify company for which the flag was checked
- `req_user` (map from string to string, optional, nullable) — Key-value pairs used to to identify user for which the flag was checked
- `rule_id` (string, optional, nullable) — Schematic rule ID (starting with 'rule_') of the rule that matched for the flag, if any
- `user_id` (string, optional, nullable) — Schematic user ID (starting with 'user_') of the user evaluated, if any

### EventBodyIdentify

- `keys` (map from string to string, required) — Key-value pairs to identify the user
- `company` (EventBodyIdentifyCompany, optional) — Information about the company associated with the user; required only if it is a new user
- `name` (string, optional) — The display name of the user being identified; required only if it is a new user
- `traits` (EventBodyIdentifyTraits, optional) — A map of trait names to trait values

### EventBodyInference

- `company` (map from string to string, required) — Key-value pairs to identify the company associated with the inference event
- `input_tokens` (long, required) — Total number of input tokens for the inference request, including those served from and written to a prompt cache
- `output_tokens` (long, required) — Number of output tokens for the inference request
- `provider` (string, required) — The inference provider (e.g. 'anthropic', 'openai')
- `response_model` (string, required) — The model that served the inference response
- `cache_creation_input_tokens` (long, optional) — Number of input tokens written to a prompt cache; a subset of input_tokens
- `cached_input_tokens` (long, optional) — Number of input tokens served from cache; a subset of input_tokens
- `cost` (string, optional) — Provided cost of the inference request as a decimal string; derived from model pricing when omitted
- `currency` (string, optional) — ISO 4217 currency code for the provided cost; defaults to 'usd'
- `event` (string, optional) — Optional track event name to fan out for usage-based billing
- `operation` (string, optional) — The inference operation; defaults to 'chat'
- `reasoning_tokens` (long, optional) — Number of reasoning tokens for the inference request
- `request_model` (string, optional) — The model requested for the inference request
- `requests` (long, optional) — Number of requests represented by this event; defaults to 1
- `user` (map from string to string, optional) — Key-value pairs to identify the user associated with the inference event

### EventBodyTrackTraits

A map of trait names to trait values

### EventBodyIdentifyCompany

Information about the company associated with the user; required only if it is a new user

- `keys` (map from string to string, required) — Key-value pairs to identify the company
- `name` (string, optional) — The display name of the company; required only if it is a new company
- `traits` (EventBodyIdentifyCompanyTraits, optional) — A map of trait names to trait values

### EventBodyIdentifyTraits

A map of trait names to trait values

### EventBodyIdentifyCompanyTraits

A map of trait names to trait values

## Examples

**Request**

```json
{
  "event_type": "flag_check"
}
```

**Response**

```json
{
  "data": {
    "captured_at": "2024-01-15T09:30:00Z",
    "remote_ip": "string",
    "user_agent": "string",
    "event_id": "string",
    "remote_addr": "string"
  },
  "params": {}
}
```

**SDK Code**

```python
import requests

url = "https://api.schematichq.com/events"

payload = { "event_type": "flag_check" }
headers = {
    "X-Schematic-Api-Key": "<apiKey>",
    "Content-Type": "application/json"
}

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

print(response.json())
```

```javascript
const url = 'https://api.schematichq.com/events';
const options = {
  method: 'POST',
  headers: {'X-Schematic-Api-Key': '<apiKey>', 'Content-Type': 'application/json'},
  body: '{"event_type":"flag_check"}'
};

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

```go
package main

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

func main() {

	url := "https://api.schematichq.com/events"

	payload := strings.NewReader("{\n  \"event_type\": \"flag_check\"\n}")

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

	req.Header.Add("X-Schematic-Api-Key", "<apiKey>")
	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
require 'uri'
require 'net/http'

url = URI("https://api.schematichq.com/events")

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

request = Net::HTTP::Post.new(url)
request["X-Schematic-Api-Key"] = '<apiKey>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"event_type\": \"flag_check\"\n}"

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

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.schematichq.com/events")
  .header("X-Schematic-Api-Key", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"event_type\": \"flag_check\"\n}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.schematichq.com/events', [
  'body' => '{
  "event_type": "flag_check"
}',
  'headers' => [
    'Content-Type' => 'application/json',
    'X-Schematic-Api-Key' => '<apiKey>',
  ],
]);

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

```csharp
using RestSharp;

var client = new RestClient("https://api.schematichq.com/events");
var request = new RestRequest(Method.POST);
request.AddHeader("X-Schematic-Api-Key", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"event_type\": \"flag_check\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "X-Schematic-Api-Key": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = ["event_type": "flag_check"] as [String : Any]

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

let request = NSMutableURLRequest(url: NSURL(string: "https://api.schematichq.com/events")! 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()
```