API Reference¶

MyPost provides a RESTful API for all functionality.

Base URL¶

https://your-domain.com/api/v1

Authentication¶

All endpoints (except auth) require a Bearer token:

curl -H "Authorization: Bearer <access_token>" \
  https://your-domain.com/api/v1/...

Authentication Endpoints¶

POST /api/v1/auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "password123"
}

Response:

{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "expiresIn": 900,
  "user": {
    "id": "uuid",
    "email": "user@example.com",
    "name": "John Doe"
  }
}

Refresh Token¶

POST /api/v1/auth/refresh
Cookie: refreshToken=...

Logout¶

POST /api/v1/auth/logout
Authorization: Bearer <token>

Get Current User¶

GET /api/v1/auth/me
Authorization: Bearer <token>

Workspaces¶

List Workspaces¶

GET /api/v1/workspaces

Response:

{
  "data": [
    {
      "id": "uuid",
      "name": "My Agency",
      "createdAt": "2026-01-01T00:00:00Z"
    }
  ]
}

Create Workspace¶

POST /api/v1/workspaces
Content-Type: application/json

{
  "name": "My Agency"
}

Get Workspace¶

GET /api/v1/workspaces/:id

Update Workspace¶

PATCH /api/v1/workspaces/:id
Content-Type: application/json

{
  "name": "Updated Name"
}

Brands¶

List Brands¶

GET /api/v1/workspaces/:workspaceId/brands

Create Brand¶

POST /api/v1/workspaces/:workspaceId/brands
Content-Type: application/json

{
  "name": "My Brand",
  "description": "Brand description"
}

Get Brand¶

GET /api/v1/brands/:id

Update Brand¶

PATCH /api/v1/brands/:id
Content-Type: application/json

{
  "name": "Updated Brand Name"
}

Delete Brand¶

DELETE /api/v1/brands/:id

GET /api/v1/brands/:brandId/social-accounts

Response:

{
  "data": [
    {
      "id": "uuid",
      "network": "facebook",
      "name": "My Page",
      "profileImageUrl": "https://...",
      "status": "active",
      "tokenExpiresAt": "2026-02-01T00:00:00Z"
    }
  ]
}

POST /api/v1/brands/:brandId/social-accounts
Content-Type: application/json

{
  "network": "facebook"
}

Response:

{
  "authUrl": "https://facebook.com/oauth/authorize?..."
}

POST /api/v1/social-accounts/:id/disconnect

POST /api/v1/social-accounts/:id/reconnect

Posts¶

List Posts¶

GET /api/v1/brands/:brandId/posts?status=draft&limit=50

Query Parameters: | Parameter | Type | Description | |-----------|------|-------------| | status | string | draft, scheduled, published, failed | | limit | number | Max results (default: 50) | | cursor | string | Pagination cursor |

Create Post¶

POST /api/v1/brands/:brandId/posts
Content-Type: application/json

{
  "content": "Hello world! 👋",
  "mediaIds": ["uuid1", "uuid2"],
  "targetAccountIds": ["account-uuid"],
  "scheduledAt": "2026-01-15T14:00:00Z"
}

Get Post¶

GET /api/v1/posts/:id

Update Post¶

PATCH /api/v1/posts/:id
Content-Type: application/json

{
  "content": "Updated content"
}

Delete Post¶

DELETE /api/v1/posts/:id

Schedule Post¶

POST /api/v1/posts/:id/schedule
Content-Type: application/json

{
  "scheduledAt": "2026-01-15T14:00:00Z"
}

Publish Now¶

POST /api/v1/posts/:id/publish-now

Cancel Scheduled Post¶

POST /api/v1/posts/:id/cancel

Media¶

Upload Media¶

Step 1: Initiate upload

POST /api/v1/brands/:brandId/media
Content-Type: application/json

{
  "filename": "image.jpg",
  "mimeType": "image/jpeg",
  "size": 1024000
}

Response:

{
  "id": "uuid",
  "uploadUrl": "https://s3.../presigned-url",
  "expiresAt": "2026-01-01T01:00:00Z"
}

Step 2: Upload to presigned URL

curl -X PUT -T image.jpg "https://s3.../presigned-url"

Step 3: Complete upload

POST /api/v1/media/:id/complete

List Media¶

GET /api/v1/brands/:brandId/media?limit=50&tag=campaign

Delete Media¶

DELETE /api/v1/media/:id

Analytics¶

Brand Overview¶

GET /api/v1/brands/:brandId/analytics/overview?from=2026-01-01&to=2026-01-31

Response:

{
  "followers": 15420,
  "followerGrowth": 523,
  "impressions": 142000,
  "engagement": 8532,
  "engagementRate": 6.01,
  "posts": 45
}

Account Analytics¶

GET /api/v1/social-accounts/:id/analytics?from=2026-01-01&to=2026-01-31

Post Analytics¶

GET /api/v1/posts/:id/analytics

Response:

{
  "impressions": 5420,
  "reach": 4200,
  "likes": 342,
  "comments": 28,
  "shares": 15,
  "clicks": 89
}

Export Analytics¶

POST /api/v1/analytics/export
Content-Type: application/json

{
  "brandId": "uuid",
  "from": "2026-01-01",
  "to": "2026-01-31",
  "format": "csv"
}

Users & Team¶

List Users¶

GET /api/v1/workspaces/:workspaceId/users

Invite User¶

POST /api/v1/workspaces/:workspaceId/users/invite
Content-Type: application/json

{
  "email": "newuser@example.com",
  "roleId": "role-uuid"
}

Update User Role¶

PATCH /api/v1/workspaces/:workspaceId/users/:userId
Content-Type: application/json

{
  "roleId": "new-role-uuid"
}

Remove User¶

DELETE /api/v1/workspaces/:workspaceId/users/:userId

Roles¶

List Roles¶

GET /api/v1/workspaces/:workspaceId/roles

Create Role¶

POST /api/v1/workspaces/:workspaceId/roles
Content-Type: application/json

{
  "name": "Content Manager",
  "permissions": [
    "posts.create",
    "posts.edit",
    "media.upload",
    "analytics.view"
  ]
}

Available Permissions¶

Permission	Description
`posts.create`	Create new posts
`posts.edit`	Edit existing posts
`posts.delete`	Delete posts
`posts.publish`	Publish posts
`posts.schedule`	Schedule posts
`media.upload`	Upload media assets
`media.delete`	Delete media assets
`brands.create`	Create brands
`brands.edit`	Edit brands
`brands.delete`	Delete brands
`accounts.connect`	Connect social accounts
`accounts.disconnect`	Disconnect accounts
`analytics.view`	View analytics
`analytics.export`	Export analytics data
`users.invite`	Invite team members
`users.manage`	Manage team members
`roles.manage`	Manage roles
`workspace.settings`	Modify workspace settings

Approval Workflows¶

Submit for Approval¶

POST /api/v1/posts/:id/submit-for-approval

Approve Post¶

POST /api/v1/approvals/:id/approve
Content-Type: application/json

{
  "comment": "Looks great!"
}

Reject Post¶

POST /api/v1/approvals/:id/reject
Content-Type: application/json

{
  "reason": "Please revise the hashtags"
}

Audit Log¶

Get Audit Events¶

GET /api/v1/audit/events?limit=100&cursor=...

Response:

{
  "data": [
    {
      "id": "uuid",
      "action": "post.published",
      "userId": "uuid",
      "resourceType": "post",
      "resourceId": "uuid",
      "createdAt": "2026-01-01T12:00:00Z",
      "metadata": {}
    }
  ],
  "page": {
    "nextCursor": "..."
  }
}

Error Responses¶

All errors follow this format:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Human readable message",
    "details": [
      {
        "path": "email",
        "message": "Invalid email format"
      }
    ],
    "requestId": "req_abc123"
  }
}

Error Codes¶

Code	HTTP Status	Description
`UNAUTHORIZED`	401	Invalid or missing token
`FORBIDDEN`	403	Insufficient permissions
`NOT_FOUND`	404	Resource not found
`VALIDATION_ERROR`	400	Invalid request data
`RATE_LIMITED`	429	Too many requests
`INTERNAL_ERROR`	500	Server error

Rate Limits¶

Scope	Limit
Global	1000 req/sec
Per Workspace	100 req/sec
Per User	10 req/sec

Rate limit headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1704067200

Pagination¶

Cursor-based pagination:

GET /api/v1/posts?limit=50&cursor=eyJpZCI6MTAwfQ==

Response:

{
  "data": [...],
  "page": {
    "nextCursor": "eyJpZCI6MTUwfQ==",
    "hasMore": true
  }
}

Webhooks¶

POST /api/v1/webhooks
Content-Type: application/json

{
  "url": "https://your-server.com/webhook",
  "events": ["post.published", "post.failed"],
  "secret": "your-signing-secret"
}

Webhook Payload¶

{
  "event": "post.published",
  "timestamp": "2026-01-01T12:00:00Z",
  "data": {
    "postId": "uuid",
    "brandId": "uuid",
    "publishedAt": "2026-01-01T12:00:00Z"
  }
}

Verify Signature¶

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from('sha256=' + expected)
  );
}

API Reference¶

Base URL¶

Authentication¶

Authentication Endpoints¶

Login¶

Refresh Token¶

Logout¶

Get Current User¶

Workspaces¶

List Workspaces¶

Create Workspace¶

Get Workspace¶

Update Workspace¶

Brands¶

List Brands¶

Create Brand¶

Get Brand¶

Update Brand¶

Delete Brand¶

Social Accounts¶

List Social Accounts¶

Connect Social Account¶

Disconnect Social Account¶

Reconnect Social Account¶

Posts¶

List Posts¶

Create Post¶

Get Post¶

Update Post¶

Delete Post¶

Schedule Post¶

Publish Now¶

Cancel Scheduled Post¶

Media¶

Upload Media¶

List Media¶

Delete Media¶

Analytics¶

Brand Overview¶

Account Analytics¶

Post Analytics¶

Export Analytics¶

Users & Team¶

List Users¶

Invite User¶

Update User Role¶

Remove User¶

Roles¶

List Roles¶

Create Role¶

Available Permissions¶

Approval Workflows¶

Submit for Approval¶

Approve Post¶

Reject Post¶

Audit Log¶

Get Audit Events¶

Error Responses¶

Error Codes¶

Rate Limits¶

Pagination¶

Webhooks¶

Subscribe to Events¶

Webhook Payload¶

Verify Signature¶