Skip to content
dropin

Patch an object (server token only)

PATCH
/v1/objects/{type}/{id}
curl --request PATCH \
  --url http://localhost:3000/v1/objects/example/example \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "set": { "custom.spots_left": 2 }, "unset": [ "custom.waitlist" ], "refs": [ "session:1234" ] }'

Merges into custom. Requires the object to exist — patching a missing object is 404, because a merge into nothing has no defined result and silently creating one would hide a tenant-side ordering bug. Use PUT to create.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
type
required
string
id
required
string

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json

Patch-style update. set and unset may both appear; unset is applied after set. Every dotted path in set/unset must begin with custom. — identity and ordering fields (actor, verb, object, target, time, foreign_id) are never patchable. At least one of set/unset/refs must be present.

object
set
object
key
additional properties
any
Example
{
  "custom.spots_left": 2
}
unset
Array<string>
Example
[
  "custom.waitlist"
]
refs

PATCH /v1/activities/{id} only — ignored on an object patch, since objects have no refs of their own. Replaces the activity’s refs array wholesale (not merged, not appended — validated identically to refs on activity creation: each entry exactly one colon, max 4, no duplicates). refs: [] is legal and clears every ref.

This is how an activity written before objects existed adopts them: PATCH it once with the refs it should resolve against. Before this field existed, the only way to attach refs to an already-posted activity was delete-and-repost — which burns its foreign_id identity, re-fans-out to every follower, and jumps it to the top of every timeline. refs carries no identity or ordering of its own (unlike time or foreign_id), so patching it does none of that: it only changes which objects resolve into the read’s sidecar.

Array<string>
<= 4 items
Example
[
  "session:1234"
]

Responses

Section titled “Responses”

200

Section titled “200”

The patched object

Media typeapplication/json

Tenant-owned mutable data that activities point at. Opaque to dropin — we store, update, and return custom, and never interpret it. Writes are server-token only.

object
type
required
string
id
required
string
custom
required
object
key
additional properties
any
updated_at
required
string format: date-time
Example
{
  "type": "session",
  "id": "1234"
}

403

Section titled “403”

Authenticated but not permitted.

Media typeapplication/json
object
error
required
object
code
required
string
Allowed values: VALIDATION_FAILED UNAUTHENTICATED FORBIDDEN NOT_FOUND CONFLICT RATE_LIMITED INTERNAL
message
required
string
requestId
required
string
fields

Present only for VALIDATION_FAILED.

Array<object>
object
path
string
message
string
Example
{
  "error": {
    "code": "VALIDATION_FAILED"
  }
}

404

Section titled “404”

Not found

Media typeapplication/json
object
error
required
object
code
required
string
Allowed values: VALIDATION_FAILED UNAUTHENTICATED FORBIDDEN NOT_FOUND CONFLICT RATE_LIMITED INTERNAL
message
required
string
requestId
required
string
fields

Present only for VALIDATION_FAILED.

Array<object>
object
path
string
message
string
Example
{
  "error": {
    "code": "VALIDATION_FAILED"
  }
}