REST API

The Max Socials REST API gives you programmatic control over every layer of the content pipeline: brands, pipelines, runs, posts, and analytics. This reference covers the endpoints available in /v1, authentication requirements, common request patterns, and the error model.

Base URL

All /v1 endpoints are served from:

https://api.maxsocials.com/v1

Every request must be made over HTTPS. Plain HTTP is rejected with 301 Moved Permanently.

Authentication

All requests require a bearer token in the Authorization header:

Authorization: Bearer <your-api-key>

API keys are scoped per organization and carry a role (read, write, or admin). Keys with the wrong scope return 403 Forbidden. See API Authentication for how to generate keys, rotate them, and sign webhook payloads.

Key Resources

The API is organized around five top-level resources. Each resource maps to a segment of the content pipeline.

Brands

A brand represents a client account managed through your organization. All other resources are scoped beneath a brand.

GET /v1/brands: list all brands visible to the authenticated key. Supports pagination via limit and cursor.
POST /v1/brands: create a new brand. Body requires name and timezone; returns the created brand object with its id.

Pipelines

A pipeline is an end-to-end content workflow attached to a brand, from trend discovery through distribution.

GET /v1/brands/:id/pipelines: list all pipelines for a brand. Returns an array of pipeline summaries including their current status (active, paused, draft).
POST /v1/pipelines/:id/runs: trigger a pipeline run immediately, bypassing the scheduled window. Returns a run object with runId and initial status: "queued". Use this for on-demand content generation or testing configuration changes.

Runs

A run is a single execution of a pipeline. Runs are asynchronous; poll or use webhooks to track completion.

GET /v1/runs/:id: return the run's current status and, once complete, the list of output post IDs. The status field progresses through queued → running → succeeded | failed. The outputs array is populated after the run reaches succeeded.

Posts

A post is a single piece of content destined for one platform channel. Posts are created automatically by pipeline runs and queued for approval or auto-publishing based on brand settings.

GET /v1/posts?status=scheduled: list posts filtered by status. Valid values: draft, pending, scheduled, published, failed. Combine with brandId to scope to a single client: ?status=scheduled&brandId=brd_01abc.
POST /v1/posts/:id/approve: approve a post that is in pending status. The post transitions to scheduled and will publish at its scheduledAt time. Returns the updated post object.

Analytics

GET /v1/analytics/runs/:id: return aggregated performance metrics for all posts produced by a run: reach, engagement rate, clicks, and estimated ROI. Metrics are populated 24–48 hours after publication as platform data becomes available.

Common Patterns

Pagination

List endpoints return a data array and a nextCursor string. To fetch the next page, pass the cursor as a query parameter:

GET /v1/brands?limit=25&cursor=eyJpZCI6Im9yZ18wMWFiYyJ9

When nextCursor is null, you have reached the last page. The default page size is 20; the maximum is 100.

Filtering

Resources that support filtering accept query parameters named after the field. Status filters use the status parameter consistently across all resources:

GET /v1/posts?status=pending&brandId=brd_01abc

Multiple values are comma-separated: ?status=pending,scheduled.

Sorting

Pass sort and order query parameters to control ordering. Default sort is createdAt descending:

GET /v1/posts?sort=scheduledAt&order=asc

Versioning

The current stable version is /v1. The versioning policy is:

Backward-compatible additions (new optional fields, new endpoints) are released into /v1 without notice. Your integration should ignore unknown fields.
Breaking changes (removed fields, changed semantics, renamed resources) are released under a new version prefix (/v2) with a minimum 90-day deprecation window for /v1.
Deprecated endpoints return a Deprecation: date="YYYY-MM-DD" response header so your observability tooling can alert on them.

Error Codes

All errors return a JSON body with error.code, error.message, and (for validation errors) error.fields. The HTTP status code is always the authoritative signal.

Status	Code	Meaning
`400`	`validation_error`	Request body or query params failed schema validation. `error.fields` lists each invalid field with a reason.
`401`	`unauthorized`	Missing or malformed `Authorization` header, or the key has been revoked.
`403`	`forbidden`	The authenticated key does not have the required scope for this operation (e.g., a `read` key calling `POST /v1/brands`).
`404`	`not_found`	The resource does not exist, or exists in a different organization and is therefore not visible to your key.
`422`	`unprocessable`	The request was well-formed but could not be executed; for example, approving a post that is already published.
`429`	`rate_limited`	Request rate exceeded. The `Retry-After` header contains the number of seconds to wait. Default limit is 120 requests per minute per API key.
`5xx`	`internal_error`	Unexpected server-side failure. Retrying with exponential backoff is safe for all `5xx` responses.

Event Subscriptions

Polling GET /v1/runs/:id works for simple integrations, but for production workflows subscribe to push events instead. Max Socials can deliver real-time notifications for events such as run.succeeded, post.published, and trend.detected. See Webhooks for endpoint registration, payload schemas, and signature verification.