Start for free
Browse docs▾

REST Tools API Reference

Direct HTTP JSON API endpoints for invoking agent tools programmatically.

In addition to MCP and the CLI, auto-social.io provides direct REST endpoints to execute agent tools from scripts, webhooks, or backend services.

Base URL

text
https://auto-social.io/api/v1/tools

All requests must be POST requests and include:

  • Authorization: Bearer <API_KEY> header.
  • Content-Type: application/json header.

Endpoints

1. List Available Tools

Retrieve tool specifications, schemas, and descriptions.

  • Endpoint: GET /api/v1/tools
  • Response: JSON array of available tools and parameter definitions.

2. Invoke a Tool

Execute an individual tool by name.

  • Endpoint: POST /api/v1/tools/:toolName
  • Body: JSON object containing tool arguments and optional metadata.

Example: List Campaigns

bash
curl -X POST https://auto-social.io/api/v1/tools/list_campaigns \  -H "Authorization: Bearer ask_..." \  -H "Content-Type: application/json" \  -d '{    "status": "active",    "detailed": true  }'

Example: List Posts

bash
curl -X POST https://auto-social.io/api/v1/tools/list_posts \  -H "Authorization: Bearer ask_..." \  -H "Content-Type: application/json" \  -d '{    "status": "draft",    "limit": 10,    "detailed": true  }'

Example: Publish Post

bash
curl -X POST https://auto-social.io/api/v1/tools/publish_post \  -H "Authorization: Bearer ask_..." \  -H "Content-Type: application/json" \  -d '{    "post_id": "00000000-0000-0000-0000-000000000000",    "integration_ids": ["11111111-1111-1111-1111-111111111111"],    "idempotency_key": "custom-uuid-key"  }'

Example: Generate image on a draft post

bash
curl -X POST https://auto-social.io/api/v1/tools/generate_image_asset \  -H "Authorization: Bearer ask_..." \  -H "Content-Type: application/json" \  -d '{    "post_id": "00000000-0000-0000-0000-000000000000",    "prompt": "Minimal product photo on white background",    "publicationType": "instagram_post",    "aspectRatio": "1:1"  }'

Example: Search product docs

bash
curl -X POST https://auto-social.io/api/v1/tools/search_docs \  -H "Authorization: Bearer ask_..." \  -H "Content-Type: application/json" \  -d '{    "query": "credits plans",    "detailed": true  }'

Example: List brands

bash
curl -X POST https://auto-social.io/api/v1/tools/list_brands \  -H "Authorization: Bearer ask_..." \  -H "Content-Type: application/json" \  -d '{"limit": 20}'

Media generation tools: generate_social_copy, generate_image_asset, generate_video_asset, generate_audio_asset. All require an existing post_id from create_post or list_posts. They consume credits (no confirmation_code). Docs search: search_docs (read-only RAG over /docs). Brand tools: see Brands.

Compact response for image, video, or audio:

json
{  "ok": true,  "compact": {    "post_id": "00000000-0000-0000-0000-000000000000",    "media_id": "11111111-1111-1111-1111-111111111111",    "kind": "image",    "url": "https://cdn.example.com/user-id/images/asset.webp",    "status": "selected"  }}

Set "detailed": true for model metadata, dimensions, and billing fields.

OpenAPI (full schemas): GET /api/v1/openapi.json.

Confirmation codes

Sensitive tools (publish_post, campaign create/update/pause/resume, live update/delete, delete_brand, and similar) respond once with:

json
{  "confirmation_required": true,  "code": "123456",  "message": "Confirmation required."}

Retry the same JSON body with "confirmation_code": "123456". Optional "idempotency_key" makes safe retries for mutations.

Standard Error Responses

Errors return standard HTTP status codes with a JSON error payload:

json
{  "error": "Post not found or unauthorized",  "status": 404}
  • 400 Bad Request: Missing required arguments or malformed JSON payload.
  • 401 Unauthorized: Missing, expired, or invalid API key.
  • 403 Forbidden: Insufficient permissions or action confirmation required.
  • 404 Not Found: Target resource does not exist in your account.
  • 429 Too Many Requests: Account rate limit exceeded.

Related: Agent guide, MCP server, CLI.