Create a user profile

⚠️

Preview — this feature is being built; the design below is the spec.

POST https://app.syntic.ai/v1/user_profiles

Create a profile for one end user of your product. Pass its id as user_profile_id when you start a session and the agent receives the person’s name, language, time zone and attributes, and its memory tool reads and writes under the profile’s memory scope. Profiles let one agent serve thousands of users without you rebuilding that context on every call.

For how this fits into a full workflow, see User profiles.

Headers

Header	Required	Value
`Authorization`	Yes	`Bearer <key>`: a private inference key (`sk_live_...`). See Authentication.
`syntic-beta`	Yes, while in preview	`agents-2026-11-01`. Without it the call fails with `400 beta_required`. See Versioning.
`Content-Type`	Yes	`application/json`
`Idempotency-Key`	No	Up to 255 characters. Retrying with the same key within 24 hours returns the first result instead of acting twice. See Idempotency.

Body parameters

Parameter	Type	Required	Notes
`external_id`	string	Yes	1 to 128 characters.
`display_name`	string	No	Up to 120 characters.
`locale`	string	No	BCP 47, for example `de-DE`.
`timezone`	string	No	IANA zone, for example `Asia/Dubai`.
`attributes`	object	No	Up to 50 keys; keys up to 64 characters, string values up to 512.
`memory_scope`	string	No	Default `user:<external_id>`.

Response

201 Created, Content-Type: application/json

{
  "id": "uprof_01JCF5H7K9M1P3R5T7V9",
  "type": "user_profile",
  "external_id": "cust-4821",
  "display_name": "Dana Lee",
  "locale": "en-GB",
  "timezone": "Europe/London",
  "attributes": {
    "plan": "gold",
    "region": "uk-south"
  },
  "memory_scope": "user:cust-4821",
  "session_count": 0,
  "created_at": "2026-10-02T09:00:00Z",
  "updated_at": "2026-10-02T09:00:00Z"
}

Field	Type	Description
`id`	string	Starts with `uprof_`.
`external_id`	string	Your own id for the person; unique within the workspace.
`locale`	string	BCP 47 tag. The agent is told to answer in this language unless the user writes in another.
`timezone`	string	IANA zone. Used for dates in the agent’s context and for deployment schedules that run per user.
`attributes`	object	Up to 50 keys, string, number or boolean values. Visible to the agent as facts about the user.
`memory_scope`	string	The scope used when agents read or write memories about this person.
`session_count`	integer	Sessions started with this profile.

Examples

curl -sS "https://app.syntic.ai/v1/user_profiles" \
  -H "Authorization: Bearer $SYNTIC_API_KEY" \
  -H "syntic-beta: agents-2026-11-01" \
  -H "Idempotency-Key: 8d6f0c1e-4b2a-4a57-9f0e-2f1d3c4b5a69" \
  -H "Content-Type: application/json" \
  -d '{
      "external_id": "cust-4821",
      "display_name": "Dana Lee",
      "locale": "en-GB",
      "timezone": "Europe/London",
      "attributes": {
        "plan": "gold",
        "region": "uk-south"
      }
    }'

import os
 
import requests
 
resp = requests.post(
    "https://app.syntic.ai/v1/user_profiles",
    headers={
        "Authorization": f"Bearer {os.environ['SYNTIC_API_KEY']}",
        "syntic-beta": "agents-2026-11-01",
        "Idempotency-Key": "8d6f0c1e-4b2a-4a57-9f0e-2f1d3c4b5a69",
    },
    json={
        "external_id": "cust-4821",
        "display_name": "Dana Lee",
        "locale": "en-GB",
        "timezone": "Europe/London",
        "attributes": {
            "plan": "gold",
            "region": "uk-south"
        }
    },
    timeout=60,
)
data = resp.json()
if not resp.ok:
    raise RuntimeError(f"{resp.status_code} {data['error']['code']}: {data['error']['message']}")
print(data)

const res = await fetch('https://app.syntic.ai/v1/user_profiles', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SYNTIC_API_KEY}`,
    'syntic-beta': 'agents-2026-11-01',
    'Idempotency-Key': '8d6f0c1e-4b2a-4a57-9f0e-2f1d3c4b5a69',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "external_id": "cust-4821",
    "display_name": "Dana Lee",
    "locale": "en-GB",
    "timezone": "Europe/London",
    "attributes": {
      "plan": "gold",
      "region": "uk-south"
    }
  }),
})
const text = await res.text()
const data = text ? JSON.parse(text) : null
if (!res.ok) throw new Error(`${res.status} ${data.error.code}: ${data.error.message}`)
console.log(data ?? res.status)

package main
 
import (
	"fmt"
	"io"
	"net/http"
	"os"
	"strings"
)
 
func main() {
	body := strings.NewReader(`{
  "external_id": "cust-4821",
  "display_name": "Dana Lee",
  "locale": "en-GB",
  "timezone": "Europe/London",
  "attributes": {
    "plan": "gold",
    "region": "uk-south"
  }
}`)
	req, err := http.NewRequest("POST", "https://app.syntic.ai/v1/user_profiles", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("SYNTIC_API_KEY"))
	req.Header.Set("syntic-beta", "agents-2026-11-01")
	req.Header.Set("Idempotency-Key", "8d6f0c1e-4b2a-4a57-9f0e-2f1d3c4b5a69")
	req.Header.Set("Content-Type", "application/json")
 
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
 
	out, _ := io.ReadAll(resp.Body)
	if resp.StatusCode >= 300 {
		panic(fmt.Sprintf("%d: %s", resp.StatusCode, out))
	}
	fmt.Println(string(out))
}

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
 
public class Example {
    public static void main(String[] args) throws Exception {
        String body = """
            {
              "external_id": "cust-4821",
              "display_name": "Dana Lee",
              "locale": "en-GB",
              "timezone": "Europe/London",
              "attributes": {
                "plan": "gold",
                "region": "uk-south"
              }
            }
            """;
        HttpRequest request = HttpRequest.newBuilder(URI.create("https://app.syntic.ai/v1/user_profiles"))
            .header("Authorization", "Bearer " + System.getenv("SYNTIC_API_KEY"))
            .header("syntic-beta", "agents-2026-11-01")
            .header("Idempotency-Key", "8d6f0c1e-4b2a-4a57-9f0e-2f1d3c4b5a69")
            .header("Content-Type", "application/json")
            .method("POST", HttpRequest.BodyPublishers.ofString(body))
            .build();
        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());
        if (response.statusCode() >= 300) {
            throw new RuntimeException(response.statusCode() + ": " + response.body());
        }
        System.out.println(response.body());
    }
}

using System.Net.Http.Headers;
using System.Text;
 
using var http = new HttpClient();
using var request = new HttpRequestMessage(new HttpMethod("POST"), "https://app.syntic.ai/v1/user_profiles");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("SYNTIC_API_KEY"));
request.Headers.Add("syntic-beta", "agents-2026-11-01");
request.Headers.Add("Idempotency-Key", "8d6f0c1e-4b2a-4a57-9f0e-2f1d3c4b5a69");
request.Content = new StringContent("""
    {
      "external_id": "cust-4821",
      "display_name": "Dana Lee",
      "locale": "en-GB",
      "timezone": "Europe/London",
      "attributes": {
        "plan": "gold",
        "region": "uk-south"
      }
    }
    """, Encoding.UTF8, "application/json");
 
using var response = await http.SendAsync(request);
var text = await response.Content.ReadAsStringAsync();
if (!response.IsSuccessStatusCode) throw new Exception($"{(int)response.StatusCode}: {text}");
Console.WriteLine(text);

<?php
$body = <<<'JSON'
{
  "external_id": "cust-4821",
  "display_name": "Dana Lee",
  "locale": "en-GB",
  "timezone": "Europe/London",
  "attributes": {
    "plan": "gold",
    "region": "uk-south"
  }
}
JSON;
 
$ch = curl_init('https://app.syntic.ai/v1/user_profiles');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('SYNTIC_API_KEY'),
        'syntic-beta: agents-2026-11-01',
        'Idempotency-Key: 8d6f0c1e-4b2a-4a57-9f0e-2f1d3c4b5a69',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
 
if ($status >= 300) {
    throw new RuntimeException("$status: $response");
}
print_r(json_decode($response, true) ?? $status);

require "json"
require "net/http"
require "uri"
 
uri = URI("https://app.syntic.ai/v1/user_profiles")
req = Net::HTTP::Post.new(uri)
req["Authorization"] = "Bearer #{ENV.fetch('SYNTIC_API_KEY')}"
req["syntic-beta"] = "agents-2026-11-01"
req["Idempotency-Key"] = "8d6f0c1e-4b2a-4a57-9f0e-2f1d3c4b5a69"
req["Content-Type"] = "application/json"
req.body = <<~'JSON'
  {
    "external_id": "cust-4821",
    "display_name": "Dana Lee",
    "locale": "en-GB",
    "timezone": "Europe/London",
    "attributes": {
      "plan": "gold",
      "region": "uk-south"
    }
  }
JSON
 
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
raise "#{res.code}: #{res.body}" unless res.is_a?(Net::HTTPSuccess)
puts res.body.empty? ? res.code : JSON.pretty_generate(JSON.parse(res.body))

Errors

Errors use the error envelope and carry a request_id. Codes specific to this operation:

Status	`type`	`code`	When
400	`invalid_request_error`	`beta_required`	The `syntic-beta` header is missing.
409	`conflict_error`	`external_id_taken`	A profile with this `external_id` exists; update it instead.
400	`invalid_request_error`	`invalid_locale`	`locale` or `timezone` is not a recognised value.
401	`authentication_error`	`invalid_api_key`	The key is missing, unknown, revoked or expired.
429	`rate_limit_error`	`rate_limited`	Too many requests; wait for `Retry-After`. See Rate-limit headers.

Delete a version List profiles

Was this page helpful?