# Overview
The REST API at a glance. Every endpoint below is generated from the contract the API runs on.
```txt
https://api.rizamo.com/v1
```
- Send JSON, get JSON. Dates are ISO 8601 in UTC, such as `2026-11-03T09:00:00Z`.
- Authenticate with your API key as a bearer token: see [Authentication](/authentication).
- Send an `Idempotency-Key` on every `POST`: see [Errors](/errors#retries).
- Ids carry their type: `prof_` for profiles, `acc_` for accounts, `post_` for posts.
- Lists answer `{ "items": [...] }`.
The whole API as one file: [openapi.json](/openapi.json).
# Authentication
API keys for your code, OAuth for AI agents.
## API keys [#api-keys]
Send your key as a bearer token on every request.
```bash
curl https://api.rizamo.com/v1/profiles \
-H "Authorization: Bearer $RIZAMO_API_KEY"
```
- Create keys in the web app, under **Developers**. A key starts with `rz_live_` and is shown once.
- A key belongs to the team, not to a person, so it keeps working when someone leaves.
- A key can be limited to some profiles and to some permissions.
- Rotating a key keeps the old one working for 24 hours.
Never put a key in a URL, a public repository or client-side code.
## AI agents [#ai-agents]
The MCP server signs in with OAuth: your agent opens a Rizamo sign-in page and you choose what it can reach. No key to copy.
# Concepts
The objects you work with in Rizamo.
## Team [#team]
Your company. It owns the billing, the members and the API keys. You never pass a team id: your key or your sign-in already belongs to one.
## Profile [#profile]
A brand or a client, such as "Café Lisboa". A profile groups the accounts you post to together. Members and keys can be limited to some profiles.
## Account [#account]
A social account connected to a profile: an Instagram business account, a Facebook Page, a TikTok account. Rizamo keeps the connection alive and tells you when it needs to be reconnected.
## Post [#post]
What you want to say: text, media, a time and your own custom fields. A post is a `draft` until you schedule it.
## Target [#target]
Where a post goes: one account and one format, such as a reel on Instagram and a story on the same account. Each target is published, fails or is edited on its own, so one network failing never blocks the others.
# Errors
One error shape for every endpoint, with what to do next.
Every error has the same shape and an HTTP status that matches it.
```json
{
"error": {
"code": "invalid_request",
"message": "scheduledAt: must be in the future",
"action": "edit_post"
},
"requestId": "req_..."
}
```
- `code`: stable, safe to branch on.
- `message`: for people. It names the fields at fault.
- `action`: what to do next: `reconnect_account`, `edit_post`, `retry` or `contact_support`.
- `network`: the network's own `code`, `subcode` and `message`, when a network refused.
- `requestId`: also in the `Request-Id` header. Send it to support.
## Codes [#codes]
| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `invalid_request` | A field is missing or wrong |
| 401 | `unauthorized` | No key, or the key is not valid |
| 403 | `forbidden` | The key cannot reach this profile or action |
| 404 | `not_found` | No such object, or not in your team |
| 409 | `conflict` | The request conflicts with the object's current state |
| 429 | `rate_limited` | Too many requests: wait for `Retry-After` seconds |
| 500 | `internal` | Our side failed. Retry, and send the `requestId` if it keeps failing |
## Retries [#retries]
Send an `Idempotency-Key` header on every `POST`. A retry with the same key gets the same answer for 24 hours, so a post is never created twice.
# Introduction
Publish, schedule and measure social posts from your code or your AI agent.
Rizamo connects your social accounts once. Your code calls the REST API, your agent calls the MCP server, your team uses the web app. All three do the same things.
Schedule your first post in three calls.
Profiles, accounts, posts and targets.
API keys for code, OAuth for agents.
Every endpoint, generated from the API itself.
## For agents [#for-agents]
- [llms.txt](/llms.txt) lists every page, [llms-full.txt](/llms-full.txt) has them all in one file.
- Every page has a Markdown copy: add `.md` to its URL.
- [openapi.json](/openapi.json) describes the whole REST API.
# Quickstart
Get an API key, find an account and schedule a post.
### Create an API key [#create-an-api-key]
In the web app, open **Developers** and create an API key. It starts with `rz_live_` and is shown once.
```bash
export RIZAMO_API_KEY=rz_live_...
```
### Find the account to post to [#find-the-account-to-post-to]
```bash
curl https://api.rizamo.com/v1/accounts \
-H "Authorization: Bearer $RIZAMO_API_KEY"
```
Each account has an `id` and the `profileId` it belongs to.
### Schedule a post [#schedule-a-post]
```bash
curl https://api.rizamo.com/v1/posts \
-H "Authorization: Bearer $RIZAMO_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"profileId": "prof_...",
"accountIds": ["acc_..."],
"text": "Hello from the Rizamo API",
"status": "scheduled",
"scheduledAt": "2026-11-03T09:00:00Z"
}'
```
The answer is the post, with one target per account. Rizamo publishes it at `scheduledAt`.
## Next [#next]
- [Concepts](/concepts): what a post and a target are.
- [Create a post](/api/posts/create): every field.
# List profiles
`GET https://api.rizamo.com/v1/profiles`
```json
{
"operationId": "profiles.list",
"summary": "List profiles",
"tags": [
"Profiles"
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"color": {
"type": "string"
},
"initials": {
"type": "string"
}
},
"required": [
"id",
"name",
"color",
"initials"
]
}
}
},
"required": [
"items"
]
}
}
}
}
}
}
```
# Create a profile
`POST https://api.rizamo.com/v1/profiles`
```json
{
"operationId": "profiles.create",
"summary": "Create a profile",
"tags": [
"Profiles"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 60
},
"color": {
"type": "string",
"pattern": "^#[0-9a-f]{6}$"
}
},
"required": [
"name"
]
}
}
}
},
"responses": {
"201": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"color": {
"type": "string"
},
"initials": {
"type": "string"
}
},
"required": [
"id",
"name",
"color",
"initials"
]
}
}
}
}
}
}
```
# List connected accounts
`GET https://api.rizamo.com/v1/accounts`
```json
{
"operationId": "accounts.list",
"summary": "List connected accounts",
"tags": [
"Accounts"
],
"parameters": [
{
"name": "profileId",
"in": "query",
"schema": {
"type": "string"
},
"allowEmptyValue": true,
"allowReserved": true
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"profileId": {
"type": "string"
},
"network": {
"enum": [
"instagram",
"facebook",
"threads",
"linkedin",
"tiktok",
"youtube",
"x",
"pinterest",
"google"
],
"type": "string"
},
"handle": {
"type": "string"
},
"name": {
"type": "string"
},
"status": {
"enum": [
"connected",
"expiring",
"disconnected"
],
"type": "string"
},
"followers": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"avatarUrl": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"profileId",
"network",
"handle",
"name",
"status",
"followers",
"avatarUrl"
]
}
}
},
"required": [
"items"
]
}
}
}
}
}
}
```
# List custom field definitions
`GET https://api.rizamo.com/v1/fields`
```json
{
"operationId": "fields.list",
"summary": "List custom field definitions",
"tags": [
"Custom fields"
],
"parameters": [
{
"name": "entity",
"in": "query",
"schema": {
"enum": [
"post"
],
"type": "string"
},
"allowEmptyValue": true,
"allowReserved": true
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string"
},
"entity": {
"enum": [
"post"
],
"type": "string"
},
"label": {
"type": "string"
},
"type": {
"enum": [
"text",
"select",
"number",
"url",
"date",
"checkbox"
],
"type": "string"
},
"options": {
"type": "array",
"items": {
"type": "string"
}
},
"description": {
"type": "string"
}
},
"required": [
"key",
"entity",
"label",
"type"
]
}
}
},
"required": [
"items"
]
}
}
}
}
}
}
```
# List posts
`GET https://api.rizamo.com/v1/posts`
```json
{
"operationId": "posts.list",
"summary": "List posts",
"tags": [
"Posts"
],
"parameters": [
{
"name": "status",
"in": "query",
"schema": {
"enum": [
"draft",
"scheduled",
"published",
"failed"
],
"type": "string"
},
"allowEmptyValue": true,
"allowReserved": true
},
{
"name": "profileId",
"in": "query",
"schema": {
"type": "string"
},
"allowEmptyValue": true,
"allowReserved": true
},
{
"name": "from",
"in": "query",
"schema": {
"type": "string",
"format": "date-time"
},
"allowEmptyValue": true,
"allowReserved": true
},
{
"name": "to",
"in": "query",
"schema": {
"type": "string",
"format": "date-time"
},
"allowEmptyValue": true,
"allowReserved": true
},
{
"name": "q",
"in": "query",
"schema": {
"type": "string"
},
"allowEmptyValue": true,
"allowReserved": true
},
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 200,
"default": 100
},
"allowEmptyValue": true,
"allowReserved": true
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"profileId": {
"type": "string"
},
"status": {
"enum": [
"draft",
"scheduled",
"published",
"failed"
],
"type": "string"
},
"text": {
"type": "string"
},
"media": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"type": {
"enum": [
"image",
"video"
],
"type": "string"
},
"url": {
"type": "string"
},
"alt": {
"type": "string"
}
},
"required": [
"id",
"type",
"url",
"alt"
]
}
},
"targets": {
"type": "array",
"items": {
"type": "object",
"properties": {
"accountId": {
"type": "string"
},
"network": {
"enum": [
"instagram",
"facebook",
"threads",
"linkedin",
"tiktok",
"youtube",
"x",
"pinterest",
"google"
],
"type": "string"
},
"text": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"status": {
"enum": [
"pending",
"published",
"failed"
],
"type": "string"
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"accountId",
"network",
"text",
"status",
"url",
"error"
]
}
},
"scheduledAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"publishedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"createdBy": {
"anyOf": [
{
"type": "object",
"properties": {
"type": {
"const": "agent"
},
"agent": {
"enum": [
"claude",
"chatgpt",
"claudecode",
"cursor",
"codex",
"gemini",
"n8n",
"make",
"zapier"
],
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"type",
"agent",
"name"
]
},
{
"type": "object",
"properties": {
"type": {
"const": "user"
},
"userId": {
"type": "string"
},
"name": {
"type": "string"
},
"initials": {
"type": "string"
}
},
"required": [
"type",
"userId",
"name",
"initials"
]
}
]
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"fields": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "null"
}
]
}
},
"metrics": {
"anyOf": [
{
"type": "object",
"properties": {
"impressions": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"reach": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"engagements": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"likes": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"comments": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"shares": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"saves": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"clicks": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"required": [
"impressions",
"reach",
"engagements",
"likes",
"comments",
"shares",
"saves",
"clicks"
]
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"profileId",
"status",
"text",
"media",
"targets",
"scheduledAt",
"publishedAt",
"createdBy",
"createdAt",
"updatedAt",
"fields",
"metrics"
]
}
}
},
"required": [
"items"
]
}
}
}
}
}
}
```
# Create a post
`POST https://api.rizamo.com/v1/posts`
```json
{
"operationId": "posts.create",
"summary": "Create a post",
"tags": [
"Posts"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"profileId": {
"type": "string"
},
"text": {
"type": "string",
"maxLength": 5000
},
"accountIds": {
"type": "array",
"minItems": 1,
"items": {
"type": "string"
}
},
"mediaIds": {
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"scheduledAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"default": null
},
"fields": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"default": {}
},
"status": {
"enum": [
"draft",
"scheduled"
],
"type": "string",
"default": "draft"
}
},
"required": [
"profileId",
"text",
"accountIds"
]
}
}
}
},
"responses": {
"201": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"profileId": {
"type": "string"
},
"status": {
"enum": [
"draft",
"scheduled",
"published",
"failed"
],
"type": "string"
},
"text": {
"type": "string"
},
"media": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"type": {
"enum": [
"image",
"video"
],
"type": "string"
},
"url": {
"type": "string"
},
"alt": {
"type": "string"
}
},
"required": [
"id",
"type",
"url",
"alt"
]
}
},
"targets": {
"type": "array",
"items": {
"type": "object",
"properties": {
"accountId": {
"type": "string"
},
"network": {
"enum": [
"instagram",
"facebook",
"threads",
"linkedin",
"tiktok",
"youtube",
"x",
"pinterest",
"google"
],
"type": "string"
},
"text": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"status": {
"enum": [
"pending",
"published",
"failed"
],
"type": "string"
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"accountId",
"network",
"text",
"status",
"url",
"error"
]
}
},
"scheduledAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"publishedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"createdBy": {
"anyOf": [
{
"type": "object",
"properties": {
"type": {
"const": "agent"
},
"agent": {
"enum": [
"claude",
"chatgpt",
"claudecode",
"cursor",
"codex",
"gemini",
"n8n",
"make",
"zapier"
],
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"type",
"agent",
"name"
]
},
{
"type": "object",
"properties": {
"type": {
"const": "user"
},
"userId": {
"type": "string"
},
"name": {
"type": "string"
},
"initials": {
"type": "string"
}
},
"required": [
"type",
"userId",
"name",
"initials"
]
}
]
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"fields": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "null"
}
]
}
},
"metrics": {
"anyOf": [
{
"type": "object",
"properties": {
"impressions": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"reach": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"engagements": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"likes": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"comments": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"shares": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"saves": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"clicks": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"required": [
"impressions",
"reach",
"engagements",
"likes",
"comments",
"shares",
"saves",
"clicks"
]
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"profileId",
"status",
"text",
"media",
"targets",
"scheduledAt",
"publishedAt",
"createdBy",
"createdAt",
"updatedAt",
"fields",
"metrics"
]
}
}
}
}
}
}
```
# Get a post
`GET https://api.rizamo.com/v1/posts/{id}`
```json
{
"operationId": "posts.get",
"summary": "Get a post",
"tags": [
"Posts"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"profileId": {
"type": "string"
},
"status": {
"enum": [
"draft",
"scheduled",
"published",
"failed"
],
"type": "string"
},
"text": {
"type": "string"
},
"media": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"type": {
"enum": [
"image",
"video"
],
"type": "string"
},
"url": {
"type": "string"
},
"alt": {
"type": "string"
}
},
"required": [
"id",
"type",
"url",
"alt"
]
}
},
"targets": {
"type": "array",
"items": {
"type": "object",
"properties": {
"accountId": {
"type": "string"
},
"network": {
"enum": [
"instagram",
"facebook",
"threads",
"linkedin",
"tiktok",
"youtube",
"x",
"pinterest",
"google"
],
"type": "string"
},
"text": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"status": {
"enum": [
"pending",
"published",
"failed"
],
"type": "string"
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"accountId",
"network",
"text",
"status",
"url",
"error"
]
}
},
"scheduledAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"publishedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"createdBy": {
"anyOf": [
{
"type": "object",
"properties": {
"type": {
"const": "agent"
},
"agent": {
"enum": [
"claude",
"chatgpt",
"claudecode",
"cursor",
"codex",
"gemini",
"n8n",
"make",
"zapier"
],
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"type",
"agent",
"name"
]
},
{
"type": "object",
"properties": {
"type": {
"const": "user"
},
"userId": {
"type": "string"
},
"name": {
"type": "string"
},
"initials": {
"type": "string"
}
},
"required": [
"type",
"userId",
"name",
"initials"
]
}
]
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"fields": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "null"
}
]
}
},
"metrics": {
"anyOf": [
{
"type": "object",
"properties": {
"impressions": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"reach": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"engagements": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"likes": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"comments": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"shares": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"saves": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"clicks": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"required": [
"impressions",
"reach",
"engagements",
"likes",
"comments",
"shares",
"saves",
"clicks"
]
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"profileId",
"status",
"text",
"media",
"targets",
"scheduledAt",
"publishedAt",
"createdBy",
"createdAt",
"updatedAt",
"fields",
"metrics"
]
}
}
}
}
}
}
```
# Update a post
`PATCH https://api.rizamo.com/v1/posts/{id}`
```json
{
"operationId": "posts.update",
"summary": "Update a post",
"tags": [
"Posts"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"text": {
"type": "string",
"maxLength": 5000
},
"status": {
"enum": [
"draft",
"scheduled"
],
"type": "string"
},
"scheduledAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"fields": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "null"
}
]
}
},
"targets": {
"type": "array",
"items": {
"type": "object",
"properties": {
"accountId": {
"type": "string"
},
"text": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"accountId",
"text"
]
}
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"profileId": {
"type": "string"
},
"status": {
"enum": [
"draft",
"scheduled",
"published",
"failed"
],
"type": "string"
},
"text": {
"type": "string"
},
"media": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"type": {
"enum": [
"image",
"video"
],
"type": "string"
},
"url": {
"type": "string"
},
"alt": {
"type": "string"
}
},
"required": [
"id",
"type",
"url",
"alt"
]
}
},
"targets": {
"type": "array",
"items": {
"type": "object",
"properties": {
"accountId": {
"type": "string"
},
"network": {
"enum": [
"instagram",
"facebook",
"threads",
"linkedin",
"tiktok",
"youtube",
"x",
"pinterest",
"google"
],
"type": "string"
},
"text": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"status": {
"enum": [
"pending",
"published",
"failed"
],
"type": "string"
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"accountId",
"network",
"text",
"status",
"url",
"error"
]
}
},
"scheduledAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"publishedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"createdBy": {
"anyOf": [
{
"type": "object",
"properties": {
"type": {
"const": "agent"
},
"agent": {
"enum": [
"claude",
"chatgpt",
"claudecode",
"cursor",
"codex",
"gemini",
"n8n",
"make",
"zapier"
],
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"type",
"agent",
"name"
]
},
{
"type": "object",
"properties": {
"type": {
"const": "user"
},
"userId": {
"type": "string"
},
"name": {
"type": "string"
},
"initials": {
"type": "string"
}
},
"required": [
"type",
"userId",
"name",
"initials"
]
}
]
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"fields": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "null"
}
]
}
},
"metrics": {
"anyOf": [
{
"type": "object",
"properties": {
"impressions": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"reach": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"engagements": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"likes": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"comments": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"shares": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"saves": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"clicks": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"required": [
"impressions",
"reach",
"engagements",
"likes",
"comments",
"shares",
"saves",
"clicks"
]
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"profileId",
"status",
"text",
"media",
"targets",
"scheduledAt",
"publishedAt",
"createdBy",
"createdAt",
"updatedAt",
"fields",
"metrics"
]
}
}
}
}
}
}
```
# List inbox threads
`GET https://api.rizamo.com/v1/inbox/threads`
```json
{
"operationId": "inbox.list",
"summary": "List inbox threads",
"tags": [
"Inbox"
],
"parameters": [
{
"name": "status",
"in": "query",
"schema": {
"enum": [
"open",
"done"
],
"type": "string"
},
"allowEmptyValue": true,
"allowReserved": true
},
{
"name": "kind",
"in": "query",
"schema": {
"enum": [
"comment",
"dm",
"mention",
"review"
],
"type": "string"
},
"allowEmptyValue": true,
"allowReserved": true
},
{
"name": "profileId",
"in": "query",
"schema": {
"type": "string"
},
"allowEmptyValue": true,
"allowReserved": true
},
{
"name": "assigneeId",
"in": "query",
"schema": {
"type": "string"
},
"allowEmptyValue": true,
"allowReserved": true
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"profileId": {
"type": "string"
},
"accountId": {
"type": "string"
},
"network": {
"enum": [
"instagram",
"facebook",
"threads",
"linkedin",
"tiktok",
"youtube",
"x",
"pinterest",
"google"
],
"type": "string"
},
"kind": {
"enum": [
"comment",
"dm",
"mention",
"review"
],
"type": "string"
},
"contact": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"handle": {
"type": "string"
},
"initials": {
"type": "string"
},
"color": {
"type": "string"
},
"avatarUrl": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"name",
"handle",
"initials",
"color",
"avatarUrl"
]
},
"postId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"preview": {
"type": "string"
},
"lastMessageAt": {
"type": "string",
"format": "date-time"
},
"unread": {
"type": "boolean"
},
"status": {
"enum": [
"open",
"done"
],
"type": "string"
},
"assignee": {
"anyOf": [
{
"anyOf": [
{
"type": "object",
"properties": {
"type": {
"const": "agent"
},
"agent": {
"enum": [
"claude",
"chatgpt",
"claudecode",
"cursor",
"codex",
"gemini",
"n8n",
"make",
"zapier"
],
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"type",
"agent",
"name"
]
},
{
"type": "object",
"properties": {
"type": {
"const": "user"
},
"userId": {
"type": "string"
},
"name": {
"type": "string"
},
"initials": {
"type": "string"
}
},
"required": [
"type",
"userId",
"name",
"initials"
]
}
]
},
{
"type": "null"
}
]
},
"sentiment": {
"enum": [
"positive",
"neutral",
"negative"
],
"type": "string"
}
},
"required": [
"id",
"profileId",
"accountId",
"network",
"kind",
"contact",
"postId",
"preview",
"lastMessageAt",
"unread",
"status",
"assignee",
"sentiment"
]
}
}
},
"required": [
"items"
]
}
}
}
}
}
}
```
# Get a thread with its messages
`GET https://api.rizamo.com/v1/inbox/threads/{id}`
```json
{
"operationId": "inbox.get",
"summary": "Get a thread with its messages",
"tags": [
"Inbox"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"thread": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"profileId": {
"type": "string"
},
"accountId": {
"type": "string"
},
"network": {
"enum": [
"instagram",
"facebook",
"threads",
"linkedin",
"tiktok",
"youtube",
"x",
"pinterest",
"google"
],
"type": "string"
},
"kind": {
"enum": [
"comment",
"dm",
"mention",
"review"
],
"type": "string"
},
"contact": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"handle": {
"type": "string"
},
"initials": {
"type": "string"
},
"color": {
"type": "string"
},
"avatarUrl": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"name",
"handle",
"initials",
"color",
"avatarUrl"
]
},
"postId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"preview": {
"type": "string"
},
"lastMessageAt": {
"type": "string",
"format": "date-time"
},
"unread": {
"type": "boolean"
},
"status": {
"enum": [
"open",
"done"
],
"type": "string"
},
"assignee": {
"anyOf": [
{
"anyOf": [
{
"type": "object",
"properties": {
"type": {
"const": "agent"
},
"agent": {
"enum": [
"claude",
"chatgpt",
"claudecode",
"cursor",
"codex",
"gemini",
"n8n",
"make",
"zapier"
],
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"type",
"agent",
"name"
]
},
{
"type": "object",
"properties": {
"type": {
"const": "user"
},
"userId": {
"type": "string"
},
"name": {
"type": "string"
},
"initials": {
"type": "string"
}
},
"required": [
"type",
"userId",
"name",
"initials"
]
}
]
},
{
"type": "null"
}
]
},
"sentiment": {
"enum": [
"positive",
"neutral",
"negative"
],
"type": "string"
}
},
"required": [
"id",
"profileId",
"accountId",
"network",
"kind",
"contact",
"postId",
"preview",
"lastMessageAt",
"unread",
"status",
"assignee",
"sentiment"
]
},
"messages": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"threadId": {
"type": "string"
},
"direction": {
"enum": [
"in",
"out"
],
"type": "string"
},
"text": {
"type": "string"
},
"at": {
"type": "string",
"format": "date-time"
},
"sentBy": {
"anyOf": [
{
"anyOf": [
{
"type": "object",
"properties": {
"type": {
"const": "agent"
},
"agent": {
"enum": [
"claude",
"chatgpt",
"claudecode",
"cursor",
"codex",
"gemini",
"n8n",
"make",
"zapier"
],
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"type",
"agent",
"name"
]
},
{
"type": "object",
"properties": {
"type": {
"const": "user"
},
"userId": {
"type": "string"
},
"name": {
"type": "string"
},
"initials": {
"type": "string"
}
},
"required": [
"type",
"userId",
"name",
"initials"
]
}
]
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"threadId",
"direction",
"text",
"at",
"sentBy"
]
}
}
},
"required": [
"thread",
"messages"
]
}
}
}
}
}
}
```
# Update a thread
`PATCH https://api.rizamo.com/v1/inbox/threads/{id}`
```json
{
"operationId": "inbox.update",
"summary": "Update a thread",
"tags": [
"Inbox"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"enum": [
"open",
"done"
],
"type": "string"
},
"unread": {
"type": "boolean"
},
"assigneeId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"profileId": {
"type": "string"
},
"accountId": {
"type": "string"
},
"network": {
"enum": [
"instagram",
"facebook",
"threads",
"linkedin",
"tiktok",
"youtube",
"x",
"pinterest",
"google"
],
"type": "string"
},
"kind": {
"enum": [
"comment",
"dm",
"mention",
"review"
],
"type": "string"
},
"contact": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"handle": {
"type": "string"
},
"initials": {
"type": "string"
},
"color": {
"type": "string"
},
"avatarUrl": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"name",
"handle",
"initials",
"color",
"avatarUrl"
]
},
"postId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"preview": {
"type": "string"
},
"lastMessageAt": {
"type": "string",
"format": "date-time"
},
"unread": {
"type": "boolean"
},
"status": {
"enum": [
"open",
"done"
],
"type": "string"
},
"assignee": {
"anyOf": [
{
"anyOf": [
{
"type": "object",
"properties": {
"type": {
"const": "agent"
},
"agent": {
"enum": [
"claude",
"chatgpt",
"claudecode",
"cursor",
"codex",
"gemini",
"n8n",
"make",
"zapier"
],
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"type",
"agent",
"name"
]
},
{
"type": "object",
"properties": {
"type": {
"const": "user"
},
"userId": {
"type": "string"
},
"name": {
"type": "string"
},
"initials": {
"type": "string"
}
},
"required": [
"type",
"userId",
"name",
"initials"
]
}
]
},
{
"type": "null"
}
]
},
"sentiment": {
"enum": [
"positive",
"neutral",
"negative"
],
"type": "string"
}
},
"required": [
"id",
"profileId",
"accountId",
"network",
"kind",
"contact",
"postId",
"preview",
"lastMessageAt",
"unread",
"status",
"assignee",
"sentiment"
]
}
}
}
}
}
}
```
# Reply in a thread
`POST https://api.rizamo.com/v1/inbox/threads/{id}/messages`
```json
{
"operationId": "inbox.reply",
"summary": "Reply in a thread",
"tags": [
"Inbox"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"text": {
"type": "string",
"minLength": 1,
"maxLength": 2000
}
},
"required": [
"text"
]
}
}
}
},
"responses": {
"201": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"threadId": {
"type": "string"
},
"direction": {
"enum": [
"in",
"out"
],
"type": "string"
},
"text": {
"type": "string"
},
"at": {
"type": "string",
"format": "date-time"
},
"sentBy": {
"anyOf": [
{
"anyOf": [
{
"type": "object",
"properties": {
"type": {
"const": "agent"
},
"agent": {
"enum": [
"claude",
"chatgpt",
"claudecode",
"cursor",
"codex",
"gemini",
"n8n",
"make",
"zapier"
],
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"type",
"agent",
"name"
]
},
{
"type": "object",
"properties": {
"type": {
"const": "user"
},
"userId": {
"type": "string"
},
"name": {
"type": "string"
},
"initials": {
"type": "string"
}
},
"required": [
"type",
"userId",
"name",
"initials"
]
}
]
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"threadId",
"direction",
"text",
"at",
"sentBy"
]
}
}
}
}
}
}
```
# Analytics overview
`GET https://api.rizamo.com/v1/analytics/overview`
```json
{
"operationId": "analytics.overview",
"summary": "Analytics overview",
"tags": [
"Analytics"
],
"parameters": [
{
"name": "days",
"in": "query",
"schema": {
"type": "integer",
"minimum": 7,
"maximum": 365,
"default": 30
},
"allowEmptyValue": true,
"allowReserved": true
},
{
"name": "profileId",
"in": "query",
"schema": {
"type": "string"
},
"allowEmptyValue": true,
"allowReserved": true
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"from": {
"type": "string",
"format": "date-time"
},
"to": {
"type": "string",
"format": "date-time"
},
"kpis": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string"
},
"label": {
"type": "string"
},
"value": {
"type": "number"
},
"previous": {
"type": "number"
},
"format": {
"enum": [
"number",
"percent"
],
"type": "string"
}
},
"required": [
"key",
"label",
"value",
"previous",
"format"
]
}
},
"series": {
"type": "array",
"items": {
"type": "object",
"properties": {
"date": {
"type": "string",
"format": "date"
},
"impressions": {
"type": "number"
},
"engagements": {
"type": "number"
},
"followers": {
"type": "number"
}
},
"required": [
"date",
"impressions",
"engagements",
"followers"
]
}
},
"byNetwork": {
"type": "array",
"items": {
"type": "object",
"properties": {
"network": {
"enum": [
"instagram",
"facebook",
"threads",
"linkedin",
"tiktok",
"youtube",
"x",
"pinterest",
"google"
],
"type": "string"
},
"impressions": {
"type": "number"
},
"engagements": {
"type": "number"
},
"followers": {
"type": "number"
},
"posts": {
"type": "number"
}
},
"required": [
"network",
"impressions",
"engagements",
"followers",
"posts"
]
}
},
"topPosts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"postId": {
"type": "string"
},
"text": {
"type": "string"
},
"network": {
"enum": [
"instagram",
"facebook",
"threads",
"linkedin",
"tiktok",
"youtube",
"x",
"pinterest",
"google"
],
"type": "string"
},
"mediaUrl": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"impressions": {
"type": "number"
},
"engagementRate": {
"type": "number"
},
"publishedAt": {
"type": "string",
"format": "date-time"
}
},
"required": [
"postId",
"text",
"network",
"mediaUrl",
"impressions",
"engagementRate",
"publishedAt"
]
}
}
},
"required": [
"from",
"to",
"kpis",
"series",
"byNetwork",
"topPosts"
]
}
}
}
}
}
}
```
# List events
`GET https://api.rizamo.com/v1/events`
```json
{
"operationId": "events.list",
"summary": "List events",
"tags": [
"Events"
],
"parameters": [
{
"name": "type",
"in": "query",
"schema": {
"enum": [
"post.created",
"post.updated",
"post.scheduled",
"post.unscheduled",
"post.published",
"post.failed",
"comment.received",
"message.received",
"message.sent",
"account.connected",
"account.expiring"
],
"type": "string"
},
"allowEmptyValue": true,
"allowReserved": true
},
{
"name": "resourceId",
"in": "query",
"schema": {
"type": "string"
},
"allowEmptyValue": true,
"allowReserved": true
},
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 200,
"default": 50
},
"allowEmptyValue": true,
"allowReserved": true
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"type": {
"enum": [
"post.created",
"post.updated",
"post.scheduled",
"post.unscheduled",
"post.published",
"post.failed",
"comment.received",
"message.received",
"message.sent",
"account.connected",
"account.expiring"
],
"type": "string"
},
"at": {
"type": "string",
"format": "date-time"
},
"actor": {
"anyOf": [
{
"anyOf": [
{
"type": "object",
"properties": {
"type": {
"const": "agent"
},
"agent": {
"enum": [
"claude",
"chatgpt",
"claudecode",
"cursor",
"codex",
"gemini",
"n8n",
"make",
"zapier"
],
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"type",
"agent",
"name"
]
},
{
"type": "object",
"properties": {
"type": {
"const": "user"
},
"userId": {
"type": "string"
},
"name": {
"type": "string"
},
"initials": {
"type": "string"
}
},
"required": [
"type",
"userId",
"name",
"initials"
]
}
]
},
{
"type": "null"
}
]
},
"summary": {
"type": "string"
},
"resource": {
"type": "object",
"properties": {
"type": {
"enum": [
"post",
"thread",
"account"
],
"type": "string"
},
"id": {
"type": "string"
}
},
"required": [
"type",
"id"
]
}
},
"required": [
"id",
"type",
"at",
"actor",
"summary",
"resource"
]
}
}
},
"required": [
"items"
]
}
}
}
}
}
}
```
# List webhook endpoints
`GET https://api.rizamo.com/v1/webhooks`
```json
{
"operationId": "webhooks.list",
"summary": "List webhook endpoints",
"tags": [
"Webhooks"
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"url": {
"type": "string",
"format": "uri"
},
"events": {
"type": "array",
"items": {
"enum": [
"post.created",
"post.updated",
"post.scheduled",
"post.unscheduled",
"post.published",
"post.failed",
"comment.received",
"message.received",
"message.sent",
"account.connected",
"account.expiring"
],
"type": "string"
}
},
"status": {
"enum": [
"active",
"failing",
"disabled"
],
"type": "string"
},
"successRate": {
"type": "number"
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"lastDeliveryAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"url",
"events",
"status",
"successRate",
"createdAt",
"lastDeliveryAt"
]
}
}
},
"required": [
"items"
]
}
}
}
}
}
}
```
# List webhook deliveries
`GET https://api.rizamo.com/v1/webhooks/deliveries`
```json
{
"operationId": "webhooks.deliveries",
"summary": "List webhook deliveries",
"tags": [
"Webhooks"
],
"parameters": [
{
"name": "endpointId",
"in": "query",
"schema": {
"type": "string"
},
"allowEmptyValue": true,
"allowReserved": true
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"endpointId": {
"type": "string"
},
"event": {
"enum": [
"post.created",
"post.updated",
"post.scheduled",
"post.unscheduled",
"post.published",
"post.failed",
"comment.received",
"message.received",
"message.sent",
"account.connected",
"account.expiring"
],
"type": "string"
},
"status": {
"enum": [
"succeeded",
"failed",
"retrying"
],
"type": "string"
},
"responseCode": {
"anyOf": [
{
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
{
"type": "null"
}
]
},
"durationMs": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"attempt": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"at": {
"type": "string",
"format": "date-time"
},
"payload": {
"type": "string"
}
},
"required": [
"id",
"endpointId",
"event",
"status",
"responseCode",
"durationMs",
"attempt",
"at",
"payload"
]
}
}
},
"required": [
"items"
]
}
}
}
}
}
}
```