Upsert a user profile's traits and value score

Writes traits (and optional valueScore) to identified_users — the same table the ingest identify path uses. The response is only returned after the D1 upsert completes (at-least-once, never fire-and-forget).

projectId MUST NOT be supplied in the body — it is always derived from the authenticated API key. Traits are validated by the same sanitizeTraits pipeline as identify (≤ 8 KiB, ≤ 2 nesting levels, dangerous keys rejected).

Auth: X-API-Key with scope profile:write (x-required-scope: profile:write).

Rate limit: 60 req/min per (projectId, IP) — over → 429.

Authorizations

ApiKeyAuth

Request Body^required

application/json

Profile upsert body. projectId MUST NOT be included — it is derived from the API key.

object

userId

required

Non-empty user/profile ID.

string

traits

required

Trait map (same sanitizeTraits rules as identify — ≤ 8 KiB, ≤ 2 levels, dangerous keys rejected).

object

key

additional properties

any

valueScore

Optional value score.

number | null

Example

1
{
2
  "userId": "uid_456",
3
  "traits": {
4
    "plan": "pro",
5
    "region": "apac"
6
  },
7
  "valueScore": 87.5
8
}

Responses

200

Profile upserted.

application/json

object

required

boolean

400

Invalid JSON or invalid payload (bad userId/traits/valueScore, or traits sanitizer rejection).

application/json

400 payload-validation error for the profile endpoint.

object

error

required

string

Allowed values: invalid_json invalid_payload

detail

Human-readable reason (present for invalid_payload).

string

Examples

1
{
2
  "error": "invalid_json"
3
}

1
{
2
  "error": "invalid_payload",
3
  "detail": "userId must be a non-empty string"
4
}

401

Missing or unresolvable API key.

application/json

object

error

required

Human-readable error message.

string

retryAfter

Seconds to wait before retrying (present on 429/503).

integer

message

string

affectedIndices

Array<integer>

Examples

1
{
2
  "error": "missing_api_key"
3
}

1
{
2
  "error": "unauthorized"
3
}

403

API key lacks the profile:write scope.

application/json

object

error

required

Human-readable error message.

string

retryAfter

Seconds to wait before retrying (present on 429/503).

integer

message

string

affectedIndices

Array<integer>

Example

1
{
2
  "error": "insufficient_scope"
3
}

404

Cross-project key (tenant isolation).

application/json

object

error

required

Human-readable error message.

string

retryAfter

Seconds to wait before retrying (present on 429/503).

integer

message

string

affectedIndices

Array<integer>

Example

1
{
2
  "error": "not_found"
3
}

429

Rate limit exceeded (60/min per project+IP).

application/json

object

error

required

Human-readable error message.

string

retryAfter

Seconds to wait before retrying (present on 429/503).

integer

message

string

affectedIndices

Array<integer>

Example

1
{
2
  "error": "rate_limited"
3
}

PUT

/api/v1/profile

1
curl --request PUT \
2
  --url https://api.retidal.com/api/v1/profile \
3
  --header 'Content-Type: application/json' \
4
  --header 'X-API-Key: <YOUR_API_KEY>' \
5
  --data '{
6
  "userId": "uid_456",
7
  "traits": {
8
    "plan": "pro",
9
    "region": "apac"
10
  },
11
  "valueScore": 87.5
12
}'

1
const url = 'https://api.retidal.com/api/v1/profile';
2
const options = {
3
  method: 'PUT',
4
  headers: {'X-API-Key': '<YOUR_API_KEY>', 'Content-Type': 'application/json'},
5
  body: '{"userId":"uid_456","traits":{"plan":"pro","region":"apac"},"valueScore":87.5}'
6
};
7

8
try {
9
  const response = await fetch(url, options);
10
  const data = await response.json();
11
  console.log(data);
12
} catch (error) {
13
  console.error(error);
14
}

1
import requests
2

3
url = "https://api.retidal.com/api/v1/profile"
4

5
payload = {
6
    "userId": "uid_456",
7
    "traits": {
8
        "plan": "pro",
9
        "region": "apac"
10
    },
11
    "valueScore": 87.5
12
}
13
headers = {
14
    "X-API-Key": "<YOUR_API_KEY>",
15
    "Content-Type": "application/json"
16
}
17

18
response = requests.put(url, json=payload, headers=headers)
19

20
print(response.json())

1
import httpx
2
import json
3

4
url = "https://api.retidal.com/api/v1/profile"
5

6
headers = {"X-API-Key": "<YOUR_API_KEY>"}
7

8
payload = json.loads("{\n  \"userId\": \"uid_456\",\n  \"traits\": {\n    \"plan\": \"pro\",\n    \"region\": \"apac\"\n  },\n  \"valueScore\": 87.5\n}")
9

10
response = httpx.put(url, headers=headers, json=payload)
11

12
print(response.json())

1
package main
2

3
import (
4
  "fmt"
5
  "strings"
6
  "net/http"
7
  "io"
8
)
9

10
func main() {
11

12
  url := "https://api.retidal.com/api/v1/profile"
13

14
  payload := strings.NewReader("{\n  \"userId\": \"uid_456\",\n  \"traits\": {\n    \"plan\": \"pro\",\n    \"region\": \"apac\"\n  },\n  \"valueScore\": 87.5\n}")
15

16
  req, _ := http.NewRequest("PUT", url, payload)
17

18
  req.Header.Add("X-API-Key", "<YOUR_API_KEY>")
19
  req.Header.Add("Content-Type", "application/json")
20

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

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

26
  fmt.Println(res)
27
  fmt.Println(string(body))
28

29
}

200Profile upserted.

1
{
2
  "ok": true
3
}

Upsert a user profile's traits and value score

Authorizations

Request Bodyrequired

Example

Responses

200

400

Examples

401

Examples

403

Example

404

Example

429

Example

Request Body^required