Reconcile standardized entity classifications

POST

https://api.aventure.vc/v1/entities/classifications/reconcile

POST

/v1/entities/classifications/reconcile

$ curl -X POST "https://api.aventure.vc/v1/entities/classifications/reconcile?actorType=agent&agentChassis=codex-cli&sourceDetail=aventure.vc&sourceProvider=TechCrunch&sourceProviderId=tc-2026-05-20-example-round&sourceProviderSlug=example-round&sourceType=requestChangeForm" \
>      -H "Authorization: Bearer <token>" \
>      -H "Content-Type: application/json" \
>      -d '{
>   "entity": [
>     {
>       "desiredJoin": [
>         {
>           "standardizedClassificationId": 1
>         }
>       ],
>       "entityId": "string",
>       "expectedHash": "string"
>     }
>   ]
> }'

1 {
2   "applied": true,
3   "failed": [
4     {
5       "entityId": "string",
6       "verified": true,
7       "message": "string",
8       "plan": {
9         "create": [
10           {
11             "standardizedClassificationId": 1,
12             "isPrimary": true
13           }
14         ],
15         "delete": [
16           1
17         ],
18         "patch": [
19           {
20             "standardizedClassificationId": 1,
21             "isPrimary": true
22           }
23         ]
24       },
25       "resultHash": "string"
26     }
27   ],
28   "stale": [
29     {
30       "entityId": "string",
31       "verified": true,
32       "message": "string",
33       "plan": {
34         "create": [
35           {
36             "standardizedClassificationId": 1,
37             "isPrimary": true
38           }
39         ],
40         "delete": [
41           1
42         ],
43         "patch": [
44           {
45             "standardizedClassificationId": 1,
46             "isPrimary": true
47           }
48         ]
49       },
50       "resultHash": "string"
51     }
52   ],
53   "succeeded": [
54     {
55       "entityId": "string",
56       "verified": true,
57       "message": "string",
58       "plan": {
59         "create": [
60           {
61             "standardizedClassificationId": 1,
62             "isPrimary": true
63           }
64         ],
65         "delete": [
66           1
67         ],
68         "patch": [
69           {
70             "standardizedClassificationId": 1,
71             "isPrimary": true
72           }
73         ]
74       },
75       "resultHash": "string"
76     }
77   ]
78 }

Reconciles each entity’s standardized classification joins to the caller’s desired exact set. The server computes the delete/patch/create diff, guards every entity with the audited expectedHash, and applies each diff in its own atomic transaction with post-apply exact-set verification. apply=false (default) returns the computed plan without writing. Stale rows are reported separately from failures and are never modified.

Reconciles each entity's standardized classification joins to the caller's desired exact set. The server computes the delete/patch/create diff, guards every entity with the audited expectedHash, and applies each diff in its own atomic transaction with post-apply exact-set verification. apply=false (default) returns the computed plan without writing. Stale rows are reported separately from failures and are never modified.

Authentication

AuthorizationBearer

User bearer token: Supabase or Clerk session JWT, Clerk OAuth access token, or Clerk personal API key

X-API-Keystring

Admin API key for system-to-system write operations

Query parameters

sourceTypeenumRequired

Write provenance source type.

sourceDetailstringRequired

Source detail or reviewer reference for the write.

sourceProviderstringOptional

Provider name for provider-native IDs or slugs.

sourceProviderIdstringOptional

Provider-native source ID.

sourceProviderSlugstringOptional

Provider-native source slug.

actorTypeenumOptional

Actor type; inferred as agent when agentChassis and agentModel are supplied, or as employee from an authenticated user JWT session.

Allowed values:

agentChassisstringOptional

Agent chassis token for agent-authored writes.

agentModelstringOptional

Agent model id for agent-authored writes.

Request

This endpoint expects an object.

entitylist of objectsRequired

Entities to reconcile; each applied independently.

applybooleanOptional

false (default) computes and returns the per-entity plan without writing; true applies each plan atomically.

Response

appliedboolean

true when apply=true executed writes; false for plan-only responses.

failedlist of objects

Rows rejected or rolled back.

stalelist of objects

Rows whose expectedHash no longer matches; resultHash is current.

succeededlist of objects

Rows planned or applied successfully.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

406

Not Acceptable Error

409

Conflict Error

415

Unsupported Media Type Error

422

Unprocessable Entity Error

429

Too Many Requests Error

500

Internal Server Error

503

Service Unavailable Error