--- title: "Agent Integration" description: "Use Octopost with AI agents like Claude, GPT, and others" --- # Agent Integration Octopost is designed to work well with AI agents. All documentation is available as raw markdown files that agents can fetch and read directly, and the REST API uses straightforward JSON requests that any HTTP-capable agent can call. ## Quick Start for Agents Every documentation page on Octopost is available as a raw `.md` file. Agents can fetch these directly to get full API details, platform-specific guides, and usage examples. ### Available Documentation URLs **API Reference:** - `https://octopost.ink/docs/api/overview.md` -- API introduction, base URL, auth format, rate limits - `https://octopost.ink/docs/api/authentication.md` -- API key generation, Bearer token usage, security - `https://octopost.ink/docs/api/posts.md` -- Create, read, update, delete, and publish posts - `https://octopost.ink/docs/api/accounts.md` -- List and manage connected social accounts - `https://octopost.ink/docs/api/presets.md` -- Publishing presets for platform groups - `https://octopost.ink/docs/api/webhooks.md` -- Webhook subscriptions for real-time events - `https://octopost.ink/docs/api/rate-limits.md` -- Rate limit details and backoff strategies - `https://octopost.ink/docs/api/errors.md` -- Error codes and handling **Platform Guides:** - `https://octopost.ink/docs/platforms/twitter.md` -- Twitter/X (280 chars, images, video, threads, polls) - `https://octopost.ink/docs/platforms/bluesky.md` -- Bluesky (300 graphemes, app passwords, facets) - `https://octopost.ink/docs/platforms/linkedin.md` -- LinkedIn (3000 chars, UGC Post API) - `https://octopost.ink/docs/platforms/mastodon.md` -- Mastodon (per-instance, content warnings, polls) - `https://octopost.ink/docs/platforms/threads.md` -- Threads (500 chars, two-step publish) - `https://octopost.ink/docs/platforms/instagram.md` -- Instagram (images/video only, no text-only posts) - `https://octopost.ink/docs/platforms/facebook.md` -- Facebook (Pages only, no personal profiles) - `https://octopost.ink/docs/platforms/tiktok.md` -- TikTok (video only, async processing) - `https://octopost.ink/docs/platforms/youtube.md` -- YouTube (video only, resumable upload, quota system) **Agent Integration:** - `https://octopost.ink/docs/agents.md` -- This page ## Agent Instructions Template Copy and paste the following block into your agent's system prompt or instructions to give it everything it needs to use Octopost: ``` # Octopost API -- Agent Quick Reference Base URL: https://api.octopost.ink/v1 Auth: Bearer token in Authorization header ## Key Endpoints POST /posts -- Create a post Body: { "content": "string", "platforms": ["twitter", "bluesky", "linkedin", "mastodon", "threads", "instagram", "facebook", "tiktok", "youtube"], "media": { "images": ["url", ...], "video": "url" }, "scheduled_for": "ISO8601 datetime", "thread": [{ "content": "string" }, ...], "platform_options": { "": { ... } } } GET /posts -- List posts. Query: ?status=published|scheduled|draft&limit=10&offset=0 GET /posts/:id -- Get a single post PUT /posts/:id -- Update a post (draft or scheduled only) DEL /posts/:id -- Delete a post POST /posts/:id/publish -- Publish a draft immediately GET /accounts -- List connected social accounts GET /presets -- List publishing presets POST /webhooks -- Subscribe to events Body: { "url": "https://...", "events": ["post.published", "post.failed"] } ## Platform Constraints - twitter: 280 chars (25k premium), images (4), video (1), threads, polls - bluesky: 300 graphemes, images (4, 1MB each), threads - linkedin: 3000 chars, images (4) - mastodon: ~500 chars (varies by instance), images (4), threads, polls, CW - threads: 500 chars, images, carousels (10), threads - instagram: NO text-only posts, images/carousels (10), Reels, 2200 char captions - facebook: Pages only, 63k chars, images (10), video - tiktok: Video ONLY, 2200 char captions, async processing - youtube: Video ONLY, 100 char title, 5000 char description, 10k quota units/day ## Full Documentation (markdown, agent-readable) Fetch these .md files for complete details: - API: https://octopost.ink/docs/api/overview.md - Posts: https://octopost.ink/docs/api/posts.md - Auth: https://octopost.ink/docs/api/authentication.md - Errors: https://octopost.ink/docs/api/errors.md - Platform guides: https://octopost.ink/docs/platforms/{platform}.md ``` ## Using with Claude Code / Claude ### Adding Octopost docs as context You can tell Claude to read the Octopost documentation directly. Claude Code can fetch the raw markdown files and use them as reference. **Option 1: Reference in your CLAUDE.md** Add to your project's `CLAUDE.md` file: ```markdown ## Octopost Integration When working with Octopost, read the API docs: - API overview: https://octopost.ink/docs/api/overview.md - Posts endpoint: https://octopost.ink/docs/api/posts.md - Platform guides: https://octopost.ink/docs/platforms/{platform}.md ``` **Option 2: Ask Claude directly** Tell Claude to fetch the docs in conversation: ``` Read the Octopost API docs at https://octopost.ink/docs/api/overview.md and https://octopost.ink/docs/api/posts.md, then help me write a script that publishes a post to Twitter and Bluesky. ``` **Option 3: Download docs locally** For offline use or faster access, download the docs into your project: ```bash mkdir -p docs/octopost curl -o docs/octopost/api.md https://octopost.ink/docs/api/overview.md curl -o docs/octopost/posts.md https://octopost.ink/docs/api/posts.md ``` Then reference them in your CLAUDE.md: ```markdown Octopost API docs are in docs/octopost/ ``` ### Example: Publishing with Claude Code ``` Using my Octopost API key oct_abc123, write a TypeScript script that: 1. Creates a post with the text "Just shipped a new feature!" 2. Publishes it to Twitter and Bluesky 3. Logs the post URLs from the response ``` Claude will use the Octopost API to generate working code: ```typescript const response = await fetch("https://api.octopost.ink/v1/posts", { method: "POST", headers: { "Authorization": "Bearer oct_abc123", "Content-Type": "application/json", }, body: JSON.stringify({ content: "Just shipped a new feature!", platforms: ["twitter", "bluesky"], }), }); const post = await response.json(); // Publish immediately const publishResponse = await fetch( `https://api.octopost.ink/v1/posts/${post.id}/publish`, { method: "POST", headers: { "Authorization": "Bearer oct_abc123", }, } ); const result = await publishResponse.json(); for (const platform of result.results) { console.log(`${platform.platform}: ${platform.postUrl}`); } ``` ## Using with Other Agents Any agent or automation tool that can make HTTP requests can use the Octopost API. The pattern is the same regardless of the agent framework: 1. **Set the base URL** to `https://api.octopost.ink/v1` 2. **Include the API key** as a Bearer token in the `Authorization` header 3. **Send JSON** with `Content-Type: application/json` 4. **Parse JSON responses** for post IDs, URLs, and status information ### Generic agent setup Give your agent these instructions: ``` To publish to social media, use the Octopost API: - Base URL: https://api.octopost.ink/v1 - Authentication: Authorization: Bearer {OCTOPOST_API_KEY} - Content-Type: application/json To create and publish a post: 1. POST /posts with {"content": "...", "platforms": ["twitter", "bluesky"]} 2. POST /posts/{id}/publish to publish immediately The response includes per-platform results with post URLs. ``` ### With tools/function calling If your agent supports function calling or tool use, define an Octopost tool: ```json { "name": "publish_to_social_media", "description": "Publish a post to one or more social media platforms via Octopost", "parameters": { "type": "object", "properties": { "content": { "type": "string", "description": "The post text content" }, "platforms": { "type": "array", "items": { "type": "string", "enum": ["twitter", "bluesky", "linkedin", "mastodon", "threads", "instagram", "facebook", "tiktok", "youtube"] }, "description": "Which platforms to publish to" }, "images": { "type": "array", "items": { "type": "string" }, "description": "Optional image URLs to attach" } }, "required": ["content", "platforms"] } } ``` ### With MCP (Model Context Protocol) If your agent supports MCP servers, you can wrap the Octopost API as an MCP server to give your agent native access to social media publishing. The API's simple REST interface maps cleanly to MCP tool definitions. ## API Key Setup for Agents ### Generating an API key 1. Go to the [Octopost Dashboard](https://octopost.ink/dashboard/settings) 2. Navigate to **Settings > API Keys** 3. Click **Create API Key** 4. Give it a descriptive name (e.g., "Claude Code agent", "GitHub Actions bot") 5. Copy the key immediately -- it will not be shown again API keys follow the format `oct_` followed by a random string. ### Security considerations - **Use separate keys for each agent or integration.** If one key is compromised, you can revoke it without affecting others. - **Do not commit API keys to version control.** Use environment variables or secret management systems. - **Store keys in environment variables:** ```bash export OCTOPOST_API_KEY="oct_your_key_here" ``` - **In CI/CD pipelines,** use your platform's secrets management (GitHub Actions secrets, Vercel environment variables, etc.). - **Rotate keys periodically.** Delete old keys and generate new ones from the dashboard. - **Monitor usage.** Check the dashboard for unexpected API activity. Each API key's usage is tracked separately. - **Revoke immediately if exposed.** If a key appears in logs, commits, or public spaces, revoke it from the dashboard and generate a new one. ### Permissions All API keys currently have full access to the account's connected platforms and posts. Scoped permissions (read-only keys, platform-restricted keys) are planned for a future release.