Activity · Contract reference
HTTP operation index
This page inventories the canonical Activity HTTP surface used by the contract beta. A machine-readable schema is not yet published as an independently versioned website artifact.
Contract status
| Property | Current value |
|---|---|
| OpenAPI version | 3.1.0 |
| API document version | 0.8.0 |
| Customer base path | /api/v1 |
| Maturity | Contract beta |
| Public realtime API | None |
| Supported SDK | None |
The core schema and HMAC model are intended for consumer beta integration. Activity does not yet publish a deprecation window, migration policy, generated client, or managed-service compatibility promise.
Authentication and responses
Every /api/v1 operation requires x-tenant-id, x-actor-id, x-feedaas-timestamp, and x-feedaas-signature. Read Sign an Activity request before calling the operations below.
GET /api/health is the only unauthenticated operation.
Success responses use resource-specific top-level keys such as post, follow, relationship, like, comment, report, or ok. Timeline and comment collections use data plus page.next_cursor.
Errors use one envelope:
{
"error": {
"code": "post_not_found",
"message": "post not found"
}
}Health
| Method | Path | Purpose |
|---|---|---|
GET | /api/health | Process and service health response |
Posts and timelines
| Method | Path | Purpose |
|---|---|---|
POST | /api/v1/posts | Publish a post for the signed actor |
PATCH | /api/v1/posts/{post_id} | Edit author-owned body, metadata, or render references |
DELETE | /api/v1/posts/{post_id} | Soft delete an author-owned post and remove its timeline entries |
GET | /api/v1/timeline/home | Read the signed actor’s materialized home timeline |
GET | /api/v1/actors/{actor_id}/posts | Read profile posts visible to the signed actor |
Publish accepts an optional idempotency_key. Reusing the key within the same tenant and actor returns the original post without repeating projection or delivery work. Timeline and profile reads use opaque cursor pagination. Read Publish and read, Ordering and rebuild, and Visibility and policy before integrating these paths.
Follow graph and relationships
| Method | Path | Purpose |
|---|---|---|
POST | /api/v1/follows | Follow or reactivate a relationship to followed_id |
DELETE | /api/v1/follows/{followed_id} | Unfollow and clear existing following entries |
POST | /api/v1/relationships/{actor_id}/mute | Mute an actor and remove their entries from caller reads |
DELETE | /api/v1/relationships/{actor_id}/mute | Restore the relationship state to active |
POST | /api/v1/relationships/{actor_id}/block | Apply bidirectional read and follow restrictions |
DELETE | /api/v1/relationships/{actor_id}/block | Delete the caller’s block edge |
These operations implement feed graph state. They do not replace host business authorization or organization membership.
Likes, comments, and replies
| Method | Path | Purpose |
|---|---|---|
POST | /api/v1/posts/{post_id}/likes | Record the signed actor’s like idempotently |
DELETE | /api/v1/posts/{post_id}/likes | Remove the signed actor’s like or confirm it absent |
GET | /api/v1/posts/{post_id}/comments | List top-level comments or replies with a cursor |
POST | /api/v1/posts/{post_id}/comments | Create a top-level comment |
PATCH | /api/v1/posts/{post_id}/comments/{comment_id} | Edit an author-owned comment |
DELETE | /api/v1/posts/{post_id}/comments/{comment_id} | Soft delete an author-owned comment and its visible reply subtree |
POST | /api/v1/posts/{post_id}/comments/{comment_id}/replies | Reply to an existing comment |
Deleting a top-level comment removes its reply subtree from comment reads and derived counters. Comment bodies and metadata remain host-shaped content inside the Activity boundary.
Reposts and shares
| Method | Path | Purpose |
|---|---|---|
POST | /api/v1/posts/{post_id}/reposts | Create a first-class shared post plus repost engagement |
POST | /api/v1/posts/{post_id}/shares | Create a shared post with optional body and render references |
Share attribution and nested rendering rules are still being hardened. render_refs stores host references without resolving identity or validating media bytes.
Viewer lifecycle
| Method | Path | Purpose |
|---|---|---|
POST | /api/v1/posts/{post_id}/hide | Hide a visible post from the signed viewer |
POST | /api/v1/posts/{post_id}/reports | Create or update the signed actor’s report record |
Hide does not delete the source post. Report does not decide moderation or change moderation_state.
Common domain errors
| Status | Codes |
|---|---|
400 | missing_tenant_id, invalid_tenant_id, invalid_followed_id, cannot_follow_self, invalid_actor_id, invalid_cursor, comment validation errors |
401 | Missing, malformed, expired, or mismatched HMAC timestamp and signature errors |
403 | not_post_author, not_comment_author, relationship_blocked |
404 | post_not_found, comment_not_found |
422 | Ash or unclassified domain validation errors |
An inaccessible post is reported as post_not_found. Do not use errors to probe cross-tenant, hidden, private, muted, or blocked resources.
Compatibility boundary
The OpenAPI artifact is the operation-level source of truth. During contract beta, clients should keep cursors opaque, avoid relying on undocumented fields, and regenerate no client without reviewing the current artifact.
The /api/v1 prefix does not mean a generally available stable API. There is no published deprecation overlap window, changelog contract, migration guide, or server-to-client compatibility matrix yet.