# Spaces, full agent guide

Read https://www.spacesos.com/llms.txt first. This file is the longer reference. The product name is Spaces.

## Plans

Free: $0, no card, 1 connected account, 500 agent actions a month, hard stop, no contact fees.
Paid: $49 a month for the first connected account, $29 a month for each extra. No contact limits and no contact fees. Yearly, 20% off: $470.40 and $278.40. 14-day trial with a card, or 30 days with a trial code. 5,000 agent actions per connected account each month, pooled, then $1 per extra 1,000. Spend cap. Emails at 80% and 100%.
Agencies: $29, $24, or $19 per account a month (1-19, 20-49, 50+), minimum 5 accounts. 30% lifetime commission on referred subscriptions the customer pays, after refunds and chargebacks, approved 30 days after payment.

An agent action is a billable read or write. Auth, health, and billing calls are free.

## Connect

POST /v1/messaging/accounts/connect-link with a channel. The person opens the url.
WhatsApp: QR code. A workspace can connect more than one number. Each number is its own account.
Telegram: QR code.
Instagram, LinkedIn, Messenger, X, Gmail, Outlook, IMAP: sign-in. If the platform asks for a second factor, the person completes it on that page.
Gmail, Outlook, and IMAP are one-to-one inboxes (list, read, send, reply, threads, attachments). They are not a bulk-email product.
Instagram covers DMs, comments on the account's posts, and a private reply from a comment into a DM when the platform allows it.
Workflows are multi-step sends on LinkedIn, Instagram, WhatsApp, and Telegram, with a delay between steps and a stop when the person replies. Every step uses the safety limits below.

If connect returns BILLING_REQUIRED, the workspace needs a plan. Free is one account and 500 actions. A paid trial is POST /v1/messaging/billing/checkout. Give the person the returned url. The trial is 14 days with a card, or 30 days with a trial code.

## MCP

Onboarding, no key. POST https://api.spacesos.com/mcp/start
GET https://api.spacesos.com/mcp/start returns this short note in plain text.
Tools: create_account {email}, verify_account {signup_id, code}.
verify_account returns api_key once, plus api_url, mcp_url, auth_header, and steps.

Main server. POST https://api.spacesos.com/mcp
Header: Authorization: Bearer spc_live_...
Server name: spaces

Tools and inputs:

- list_messaging_accounts. No input. Output: {accounts:[{id, channel, name, status, connected_at}]}.
- list_messaging_chats {account_id, cursor?, limit?, unread?}. Output: {chats, next_cursor}.
- list_messaging_messages {account_id, chat_id, cursor?, limit?}.
- get_messaging_attachment {account_id, chat_id, message_id, attachment_id}. One attachment, base64, up to 5 MB. Use it for images, files, voice, video, and GIFs.
- reply_in_chat {account_id, chat_id, text?, attachments?, idempotency_key}. Scope messages:send.
- start_chat {account_id, to:{phone?|username?|user_id?}, text?, attachments?, idempotency_key}. WhatsApp: phone in international form. Instagram, Telegram, and X: username. LinkedIn: public id or profile URL. Messenger: user_id.
- create_messaging_connect_link {channel} or {account_id} to reconnect. Scope accounts:manage. Output: {url, expires_at}.
- disconnect_messaging_account {account_id, confirm:true}.
- get_messaging_billing. Read-only totals and status.
- create_messaging_billing_checkout {success_url, cancel_url}. Output: {url}.
- get_profile {account_id, identifier}.
- LinkedIn writes and reads: send_invitation, list_invitations, cancel_invitation, search_linkedin, list_user_posts, get_post, list_comments, create_post, comment_on_post, react_to_post. Writes need idempotency_key.

## REST

Base https://api.spacesos.com/v1. Header Authorization: Bearer. Sends need an Idempotency-Key header (8 to 128 letters, digits, dots, dashes, or colons).

- POST /signup {"email"}
- POST /signup/verify {"signup_id","code"}
- GET /messaging/accounts
- POST /messaging/accounts/connect-link {"channel","success_url?","failure_url?"}
- POST /messaging/accounts/{account_id}/reconnect-link
- DELETE /messaging/accounts/{account_id}
- GET /messaging/accounts/{account_id}/chats
- GET /messaging/accounts/{account_id}/chats/{chat_id}/messages
- GET /messaging/accounts/{account_id}/chats/{chat_id}/messages/{message_id}/attachments/{attachment_id}
- POST /messaging/accounts/{account_id}/chats {"to","text"}
- POST /messaging/accounts/{account_id}/chats/{chat_id}/messages {"text"}
- GET /messaging/accounts/{account_id}/users/{identifier}
- LinkedIn: invitations, search, posts, comments, and reactions under /messaging/accounts/{account_id}/
- GET /messaging/billing
- POST /messaging/billing/checkout {"success_url","cancel_url"}
- GET /messaging/usage
- POST /messaging/webhooks, GET /messaging/webhooks, DELETE /messaging/webhooks/{id}
- GET /keys, POST /keys {"name"}, DELETE /keys/{id}, POST /keys/{id}/pause, POST /keys/{id}/resume

OpenAPI: https://api.spacesos.com/openapi.json

## Errors

- 401 missing or bad key
- 402 BILLING_REQUIRED: start checkout, or the free allowance is used up
- 403 missing scope, KEY_SUSPENDED, or ACCOUNT_SUSPENDED
- 404 account, chat, or person not found
- 409 idempotency key reused for a different body
- 429 over a limit. Body retry_after_seconds. Header Retry-After. Nothing was sent.
- 502 or 503 channel unavailable. Nothing was sent. Retry later.

## Webhooks

POST /v1/messaging/webhooks with {"url":"https://..."}. New messages are posted to that url. A repeated delivery of the same event is not a second message.

## Clients

- Claude Code: claude mcp add --transport http spaces https://api.spacesos.com/mcp --header "Authorization: Bearer spc_live_..."
- Claude Desktop: MCP url https://api.spacesos.com/mcp and header Authorization Bearer spc_live_...
- ChatGPT: custom MCP connector, same url and header
- Cursor: MCP server named spaces, same url and header
- Grok: same url and header
- Onboarding: claude mcp add --transport http spaces-start https://api.spacesos.com/mcp/start

## Account safety

Spaces reduces ban risk with enforced limits, warm-up, pacing and auto-pause. It cannot guarantee the platform will not restrict the account. Do not work around a limit. On 429, wait retry_after_seconds and retry with the same Idempotency-Key. If the account is paused, stop. Check GET /v1/messaging/usage or get_messaging_usage before bulk work. A send returns account_safety: remaining_today, remaining_this_week, paused, reason.

## Safety limits, per account

WhatsApp: 15 seconds between messages, 200 a day, new chats 5 an hour and 10 a day. None for 24 hours after connecting, then 1 an hour and 3 a day in the first week.
Instagram: 15 seconds, 80 a day, new chats 6 an hour and 20 a day (2 an hour and 8 a day in week one).
LinkedIn: 20 seconds, 100 messages a day, new chats 8 an hour and 30 a day (8 a day in week one). A normal message is for a 1st-degree connection. inmail true sends an InMail. Invitations 5 an hour, 20 a day, 100 a week (5 a day in week one). Profile views 80 a day. Searches 30 a day. Comments 30 a day. Reactions 50 a day. Posts 3 a day.
Messenger: 20 seconds, 40 a day, new chats 3 an hour and 8 a day (1 an hour and 3 a day in week one).
Telegram: 20 seconds, 80 a day, new chats 5 an hour and 20 a day (8 in the first week).
X: 20 seconds, 100 a day, new chats 20 a day (10 in the first week).
Gmail, Outlook, IMAP: 20 seconds, 80 a day, 40 new threads a day, one email at a time.

Replies in an existing chat are not held by first-week new-chat limits. Do not work around a 429. Read GET /messaging/usage before a large run. Message only people who expect the account owner. No bulk cold outreach.

## Pages

- https://www.spacesos.com/docs
- https://www.spacesos.com/docs/agents
- https://www.spacesos.com/llms.txt
- https://www.spacesos.com/llms-full.txt
- https://www.spacesos.com/openapi.json
- https://www.spacesos.com/.well-known/mcp.json
- https://api.spacesos.com/llms.txt
- https://api.spacesos.com/llms-full.txt
- https://api.spacesos.com/openapi.json
- https://api.spacesos.com/.well-known/mcp.json
- https://app.spacesos.com/docs
- https://app.spacesos.com/docs/agents
- https://app.spacesos.com/llms.txt