Add an activity to a feed

POST

/v1/feeds/{group}/{id}/activities

curl --request POST \
  --url http://localhost:3000/v1/feeds/example/example/activities \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "actor": "example", "verb": "example", "object": "example", "target": "example", "foreign_id": "example", "time": "2026-04-15T12:00:00Z", "custom": {} }'

Authorizations

• bearerAuth

Parameters

Path Parameters

group

required

string

id

required

string

Request Body^required

Media typeapplication/json

object

actor

Ignored and overwritten for user tokens (spec §5).

string

verb

required

string

object

required

string

target

string | null

foreign_id

string | null

time

For user tokens, clamped to [now - 10 min, now] (spec §5): retries with the same (foreign_id, time) dedupe; future-pinning is impossible. Server tokens pass it through unclamped.

string format: date-time

custom

object

key

additional properties

any

Example^generated

{
  "actor": "example",
  "verb": "example",
  "object": "example",
  "target": "example",
  "foreign_id": "example",
  "time": "2026-04-15T12:00:00Z",
  "custom": {}
}

Responses

201

Created — or, on a (foreign_id, time) duplicate of a live activity, the existing row unchanged (idempotent, no second fan-out).

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>

Example

{
  "actor": "user:alice",
  "verb": "post",
  "object": "workout:123",
  "origin_feed": "user:alice",
  "reaction_counts": {
    "like": 3
  },
  "own_reactions": [
    "like"
  ]
}

401

Invalid, expired, revoked, or absent token.

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

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

409

The (foreign_id, time) identity belongs to a soft-deleted activity. The identity is burned — pick a new one (spec §6).

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

429

Rate limit exceeded.

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

Headers

Retry-After

integer