Social
Package social is posting to every social account you own, now or on a schedule.
Package social is posting to every social account you own, now or on a schedule.
| Base URL | https://api.hanzo.ai |
| Operations | 13 |
| Auth | Authorization: Bearer $HANZO_API_KEY |
social
GET /v1/social/accounts/{id}
Read one connected account
Returns one of the org's connected accounts by id — its network, handle, status and timestamps — or 404. The provider access token is not part of the response.
A validated principal is required; 403 without one. Every row is keyed by the caller's org taken from that principal and never from the request, so an id belonging to another tenant reads as not found rather than as a refusal.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes |
PUT /v1/social/accounts/{id}
Replace one connected account
Replaces the account's network, handle and status with what the body carries, and answers with the stored row.
This is a REPLACEMENT, not a merge, which is the rule most easily got wrong: a field the body omits is written as its default, so leaving out the handle blanks it and leaving out the status resets it to connected. Send the whole record. The same vocabularies as create apply, and an unknown network or status is refused rather than coerced.
A validated principal is required; 403 without one. Every row is keyed by the caller's org taken from that principal and never from the request, so an id belonging to another tenant reads as not found rather than as a refusal.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes |
DELETE /v1/social/accounts/{id}
Disconnect one account
Removes one connected account from the org and answers 204 with no body; an id that is not there is 404.
It removes the account record only. Posts that already published through it keep their published state and their recorded external ids — this does not retract anything from the network.
A validated principal is required; 403 without one. Every row is keyed by the caller's org taken from that principal and never from the request, so an id belonging to another tenant reads as not found rather than as a refusal.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes |
GET /v1/social/accounts
List the social accounts connected to your org
Returns the org's connected accounts — each one's id, network, handle, status and timestamps. provider filters to one network; limit bounds the page, defaulting to 200 and capped at 1000.
An account's provider access token is NEVER included in any response on this surface. Only the publisher reads it.
A validated principal is required; 403 without one. Every row is keyed by the caller's org taken from that principal and never from the request, so an id belonging to another tenant reads as not found rather than as a refusal.
POST /v1/social/accounts
Connect a social account to your org
Records a social account for the org and answers 201 with the stored row, including the generated id later calls address it by.
provider must be one of x, facebook, instagram, linkedin, tiktok, youtube or threads, defaulting to x when omitted. status is one of connected, disconnected or error, defaulting to connected. The handle is trimmed and bounded at 1024 characters.
A validated principal is required; 403 without one. Every row is keyed by the caller's org taken from that principal and never from the request, so an id belonging to another tenant reads as not found rather than as a refusal.
POST /v1/social/posts/{id}/publish
Publish one post now
Publishes the post immediately to the connected accounts on its channel and answers with the updated row, carrying the account and external id it published under.
It is IDEMPOTENT: a post that has already published, or that another caller is publishing right now, comes back unchanged rather than being posted twice. That claim is taken before any network call, which is what makes a double submit safe.
The two failure shapes differ on purpose. Having no connected account for the channel is the caller's to fix, so it is recorded ON the post as failed with the reason and answers normally. A deployment that lacks the network's own credentials cannot publish for anyone, so that is a 503 naming exactly what is missing.
A validated principal is required; 403 without one. Every row is keyed by the caller's org taken from that principal and never from the request, so an id belonging to another tenant reads as not found rather than as a refusal.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes |
GET /v1/social/posts/{id}
Read one post
Returns one of the org's posts by id, with its current status, scheduled time, media and — once it has published — the account and external id it published under. 404 when there is no such post for this org.
A validated principal is required; 403 without one. Every row is keyed by the caller's org taken from that principal and never from the request, so an id belonging to another tenant reads as not found rather than as a refusal.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes |
PUT /v1/social/posts/{id}
Replace one post
Replaces the post's content, channel, status, scheduled time and media with what the body carries, and answers with the stored row.
A REPLACEMENT, not a merge: an omitted field is written as its default, so omitting media clears it and omitting the status resets the post to draft. content is required on every update. Unlike create, this never triggers a publish — moving a post's scheduled time into the past here leaves it for the scheduler; publish now is its own operation.
A validated principal is required; 403 without one. Every row is keyed by the caller's org taken from that principal and never from the request, so an id belonging to another tenant reads as not found rather than as a refusal.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes |
DELETE /v1/social/posts/{id}
Delete one post
Removes one post from the org and answers 204 with no body; an id that is not there is 404.
It deletes the record here only. A post that has already published is not retracted from the network by deleting it.
A validated principal is required; 403 without one. Every row is keyed by the caller's org taken from that principal and never from the request, so an id belonging to another tenant reads as not found rather than as a refusal.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes |
GET /v1/social/posts
List your org's posts
Returns the org's posts — content, channel, status, scheduled time, media and timestamps. status filters to one of draft, scheduled, published or failed; limit bounds the page, defaulting to 200 and capped at 1000.
A validated principal is required; 403 without one. Every row is keyed by the caller's org taken from that principal and never from the request, so an id belonging to another tenant reads as not found rather than as a refusal.
POST /v1/social/posts
Create a post, and publish it if it is already due
Stores a post for the org and answers 201 with the stored row.
A post created as scheduled for a time that has already passed is published IMMEDIATELY, and the row returned carries that outcome — this is the one behaviour a reader would otherwise miss. A future-scheduled post is left for the scheduler, and a draft is left alone. Publishing never fails the creation: the post is stored either way, and a publish that could not run leaves the row for the scheduler to retry.
content is required and bounded at 8192 characters; channel is one of the seven supported networks, defaulting to x; status is one of draft, scheduled, published or failed, defaulting to draft; up to 10 media URLs are kept, each bounded at 1024 characters.
A validated principal is required; 403 without one. Every row is keyed by the caller's org taken from that principal and never from the request, so an id belonging to another tenant reads as not found rather than as a refusal.
GET /v1/social/providers
Which networks this deployment can actually publish to
Reports each supported network's publish-readiness: whether this deployment holds the OAuth application credentials for it and, when it does not, exactly which environment variables are missing.
This is a live read of the deployment's own configuration, not a static list of networks — it answers "can I connect this today", which is what a connect affordance and a pre-cutover checklist both need. It says nothing about whether the caller has connected an account; that is the accounts listing.
A validated principal is required; 403 without one. Every row is keyed by the caller's org taken from that principal and never from the request, so an id belonging to another tenant reads as not found rather than as a refusal.
GET /v1/social/summary
Counts across your org's social presence
Returns four counts for the caller's org: total posts, how many are scheduled, how many have published, and how many accounts are connected. It is the dashboard roll-up, computed over the org's own rows in one read.
A validated principal is required; 403 without one. Every row is keyed by the caller's org taken from that principal and never from the request, so an id belonging to another tenant reads as not found rather than as a refusal.
How is this guide?