Skip to content
dropin

Patch an activity's custom and/or refs

PATCH
/v1/activities/{id}

Permitted when origin_feed = "user:" + sub, or for any server token — the same authority rule as delete. Sets edited_at. Never touches time, so feed order and live cursors are unaffected. Fires no webhook. See PatchBody.refs for backfilling refs onto an activity posted before objects existed.

Authorizations

Section titled “Authorizations”

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 activity

Media typeapplication/json
object
id
required
string format: uuid
actor
required
string
verb
required
string
object
required
string
target
string | null
foreign_id
string | null
time
required
string format: date-time
custom
required
object
key
additional properties
any
origin_feed
required
string
reaction_counts
required
object
key
additional properties
integer
actor_user

Enriched from users.custom when actor parses as user:. Null otherwise.

object | null
own_reactions

Omitted for server tokens — no caller identity.

Array<string>
refs
required

Objects this activity points at, as type:id. Resolved into the feed read’s objects sidecar. Max 4, no duplicates.

Array<string>
edited_at
required

Null until the activity is first patched.

string | null format: date-time
version
required

Row version. Starts at 1 and increments on ANY change to this activity — a patch, a reaction count moving, a soft delete. Compare it against the copy you hold to decide whether to re-render; edited_at marks patches only, so it cannot report the field that changes most.

integer
warnings

Non-fatal problems with the activity that was just WRITTEN. Present only on the response to POST /v1/feeds/{group}/{id}/activities; a feed read never carries it — the read path stays exactly three statements.

actor_user_unresolved: the write succeeded, but actor names a user:<id> with no users row, so actor_user is null and every card renders with no name and no avatar until that user is upserted. Without this field a correct write and a broken one are byte-identical. A non-user: actor (system:jobs) never enriches by design and is NOT warned about.

Array<string>
Allowed values: actor_user_unresolved
Example
{
  "actor": "user:alice",
  "verb": "post",
  "object": "workout:123",
  "origin_feed": "user:alice",
  "reaction_counts": {
    "like": 3
  },
  "own_reactions": [
    "like"
  ],
  "refs": [
    "session:1234"
  ],
  "warnings": [
    "actor_user_unresolved"
  ]
}

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"
  }
}