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:

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:

## 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:

Option 3: Download docs locally

For offline use or faster access, download the docs into your project:

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:

Octopost API docs are in docs/octopost/

Example: Publishing with Claude Code

Claude will use the Octopost API to generate working code:

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:

With tools/function calling

If your agent supports function calling or tool use, define an Octopost tool:

{
  "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
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:

  export OCTOPOST_API_KEY="oct_your_key_here"

  Copy
• 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.