API Reference

Complete API v1 documentation for authentication, publishing, and scheduling

Overview

The xAIcreator API v1 provides a RESTful interface for multi-platform authentication, content publishing, scheduling, and account management. All endpoints use API Key authentication for secure access.

Base URL: https://xaicreator.com/api/v1

Authentication

All API requests require an API Key passed via the xai-key header:

curl "https://xaicreator.com/api/v1/twitter/drafts" \
  -H "xai-key: your_api_key_here"

Getting Your API Key

POST /api/v1/auth/login

Email login for existing users only. Does not support new user registration.

curl -X POST "https://xaicreator.com/api/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "yourpassword"
  }'

Response (Success):

{
  "success": true,
  "user": {
    "uuid": "user-uuid",
    "email": "[email protected]"
  },
  "apiKey": {
    "key": "sk-xxxxx...",
    "name": "Default API Key",
    "createdAt": "2026-01-15T10:00:00Z",
    "lastUsed": null
  },
  "warning": "Please save your API key securely. This is the only time the full key will be displayed."
}

2. Google OAuth

Step 1: Get OAuth URL

POST /api/v1/auth/oauth/google/url

curl -X POST "https://xaicreator.com/api/v1/auth/oauth/google/url" \
  -H "Content-Type: application/json" \
  -d '{"redirectUri": "http://localhost:3000/oauth-callback"}'

Response:

{
  "success": true,
  "authUrl": "https://accounts.google.com/o/oauth2/v2/auth?client_id=...",
  "state": "server-generated-state"
}

Step 2: OAuth Callback

POST /api/v1/auth/oauth/google/callback

curl -X POST "https://xaicreator.com/api/v1/auth/oauth/google/callback" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "authorization-code-from-google",
    "state": "state-from-step-1"
  }'

Response (New User):

{
  "success": true,
  "user": {
    "uuid": "new-user-uuid",
    "email": "[email protected]",
    "provider": "google",
    "isNewUser": true
  },
  "apiKey": {
    "key": "sk-new-user-key...",
    "name": "Default API Key",
    "createdAt": "2026-01-15T10:00:00Z",
    "lastUsed": null
  }
}

3. Twitter OAuth

Step 1: Get OAuth URL

POST /api/v1/auth/oauth/twitter/url

curl -X POST "https://xaicreator.com/api/v1/auth/oauth/twitter/url" \
  -H "Content-Type: application/json" \
  -d '{"redirectUri": "http://localhost:3000/oauth-callback?provider=twitter"}'

Response:

{
  "success": true,
  "authUrl": "https://x.com/i/oauth2/authorize?client_id=...",
  "state": "base64url-encoded-state"
}

Step 2: OAuth Callback

POST /api/v1/auth/oauth/twitter/callback

curl -X POST "https://xaicreator.com/api/v1/auth/oauth/twitter/callback" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "authorization-code-from-twitter",
    "state": "state-from-step-1"
  }'

Important: The complete API Key is only displayed once during registration/login. Save it immediately.

API Key Management

Get API Keys

GET /api/v1/auth/api-keys

curl "https://xaicreator.com/api/v1/auth/api-keys" \
  -H "xai-key: sk-your-api-key"

Response:

{
  "success": true,
  "apiKeys": [
    {
      "id": "key-uuid-1",
      "key": "sk-xxxx...abcd",
      "name": "Default API Key",
      "status": "created",
      "lastUsed": "2026-01-15T10:00:00Z",
      "createdAt": "2026-01-14T08:00:00Z"
    }
  ]
}

Create API Key

POST /api/v1/auth/api-keys

curl -X POST "https://xaicreator.com/api/v1/auth/api-keys" \
  -H "Content-Type: application/json" \
  -H "xai-key: sk-your-api-key" \
  -d '{"name": "New API Key"}'

Delete API Key

DELETE /api/v1/auth/api-keys/:keyId

curl -X DELETE "https://xaicreator.com/api/v1/auth/api-keys/key-uuid-3" \
  -H "xai-key: sk-your-api-key"

Twitter OAuth 2.0

Initiate Twitter OAuth

POST /api/v1/twitter/auth

curl -X POST "https://xaicreator.com/api/v1/twitter/auth" \
  -H "Content-Type: application/json" \
  -H "xai-key: your_api_key" \
  -d '{
    "socialSetId": "your-social-set-id",
    "mode": "add_to_existing"
  }'

Parameters:

Parameter	Type	Required	Description
`socialSetId`	`string`	`No`	Social Set ID to bind the account
`mode`	`string`	`No`	`"create_new"` or `"add_to_existing"` (default)
`followOnX`	`boolean`	`No`	Whether to follow on X after authorization

Response:

{
  "authUrl": "https://x.com/i/oauth2/authorize?...",
  "sessionId": "session_uuid_here"
}

Twitter OAuth Callback

GET /api/v1/twitter/callback

After user authorization, Twitter redirects to your callback URL with code and state parameters.

curl "https://xaicreator.com/api/v1/twitter/callback?code=xxx&state=xxx"

Response:

{
  "success": true,
  "accountUuid": "account_uuid",
  "socialSetId": "social_set_id"
}

Drafts Management

List Drafts

GET /api/v1/twitter/drafts

curl "https://xaicreator.com/api/v1/twitter/drafts?socialSetId=xxx" \
  -H "xai-key: your_api_key"

Response:

{
  "drafts": [
    {
      "id": "draft_uuid",
      "title": "My Draft",
      "status": "draft",
      "tweets": [...],
      "createdAt": "2026-01-14T07:21:26.000Z"
    }
  ]
}

Create Draft

POST /api/v1/twitter/drafts

curl -X POST "https://xaicreator.com/api/v1/twitter/drafts" \
  -H "Content-Type: application/json" \
  -H "xai-key: your_api_key" \
  -d '{
    "title": "My Draft",
    "tweets": [{"content": "<p>Hello from API!</p>"}],
    "socialSetId": "social-set-id",
    "scheduledFor": "2026-01-15T10:00:00Z"
  }'

Parameters:

Parameter	Type	Required	Description
`title`	`string`	`Yes`	Draft title
`tweets`	`array`	`Yes`	Array of tweet objects with `content` field (HTML supported)
`socialSetId`	`string`	`No`	Associated Social Set ID
`status`	`string`	`No`	Draft status (default: `"draft"`)
`scheduledFor`	`string`	`No`	ISO 8601 datetime for scheduled publishing
`selectedAccountIds`	`array`	`No`	Account IDs to publish to
`templateId`	`string`	`No`	Template ID if created from template

Response:

{
  "draft": {
    "id": "draft_uuid",
    "title": "My Draft",
    "status": "draft",
    "scheduledFor": null,
    "socialSetId": "social-set-id",
    "selectedAccountIds": [],
    "tweets": [
      {
        "id": "tweet_uuid",
        "content": "<p>Hello from API!</p>",
        "plainText": "Hello from API!",
        "media": [],
        "characterCount": 16,
        "isValid": true,
        "position": 0
      }
    ],
    "createdAt": "2026-01-14T07:21:26.000Z",
    "updatedAt": "2026-01-14T07:21:26.000Z"
  }
}

Publishing

Publish to Twitter

POST /api/v1/twitter/publish

curl -X POST "https://xaicreator.com/api/v1/twitter/publish" \
  -H "Content-Type: application/json" \
  -H "xai-key: your_api_key" \
  -d '{
    "draftId": "draft_uuid",
    "accountIds": ["account_id"]
  }'

Parameters:

Parameter	Type	Required	Description
`draftId`	`string`	`Yes`	Draft ID to publish
`accountIds`	`array`	`No`	Specific account IDs
`jobId`	`string`	`No`	Custom job ID for tracking
`community`	`object`	`No`	Community metadata (`{id, name, description}`)

Quote Tweet

POST /api/v1/twitter/quote

curl -X POST "https://xaicreator.com/api/v1/twitter/quote" \
  -H "Content-Type: application/json" \
  -H "xai-key: your_api_key" \
  -d '{
    "content": "Great insight!",
    "quoteTweetId": "quoted_tweet_id",
    "accountId": "your_account_id"
  }'

Response:

{
  "success": true,
  "message": "Quote posted successfully",
  "tweetId": "new_tweet_id",
  "url": "https://x.com/user/status/new_tweet_id"
}

Multi-Platform Publishing

POST /api/v1/publish/multi-platform

Publish to multiple platforms (Twitter, Bluesky, Mastodon, Threads, LinkedIn) simultaneously.

curl -X POST "https://xaicreator.com/api/v1/publish/multi-platform" \
  -H "Content-Type: application/json" \
  -H "xai-key: your_api_key" \
  -d '{
    "draftId": "draft_uuid",
    "targetAccounts": [
      {
        "accountId": "twitter_account_id",
        "platform": "twitter",
        "communityId": "community_id"
      },
      {
        "accountId": "bluesky_account_id",
        "platform": "bluesky"
      },
      {
        "accountId": "mastodon_account_id",
        "platform": "mastodon"
      },
      {
        "accountId": "threads_account_id",
        "platform": "threads"
      },
      {
        "accountId": "linkedin_account_id",
        "platform": "linkedin"
      }
    ]
  }'

Parameters:

Parameter	Type	Required	Description
`draftId`	`string`	`Yes`	Draft UUID
`targetAccounts`	`array`	`Yes`	Target account list
`targetAccounts[].accountId`	`string`	`Yes`	Account UUID
`targetAccounts[].platform`	`string`	`Yes`	Platform: `twitter`, `bluesky`, `mastodon`, `threads`, `linkedin`
`targetAccounts[].communityId`	`string`	`No`	Community ID (Twitter only)

Response:

{
  "success": true,
  "results": [
    {
      "accountId": "account_uuid",
      "platform": "twitter",
      "success": true,
      "data": { "tweetId": "...", "url": "..." }
    },
    {
      "accountId": "account_uuid",
      "platform": "bluesky",
      "success": true,
      "data": { "uri": "at://...", "cid": "..." }
    }
  ],
  "summary": {
    "total": 2,
    "succeeded": 2,
    "failed": 0
  }
}

Cost: 10 credits per platform

Platform-Specific Publishing

Bluesky

POST /api/v1/bluesky/publish

curl -X POST "https://xaicreator.com/api/v1/bluesky/publish" \
  -H "Content-Type: application/json" \
  -H "xai-key: your_api_key" \
  -d '{
    "accountUuid": "account_uuid",
    "type": "single",
    "text": "Hello Bluesky!",
    "langs": ["en"]
  }'

Parameters:

Parameter	Type	Required	Description
`accountUuid`	`string`	`Yes`	Account UUID
`type`	`string`	`Yes`	`single` or `thread`
`text`	`string`	`No*`	Post content (required for single)
`texts`	`array`	`No*`	Thread posts (required for thread)
`imageUrls`	`array`	`No`	Image URLs
`langs`	`array`	`No`	Language tags (default: `["en"]`)

Cost: 10 credits

Mastodon

POST /api/v1/mastodon/publish

curl -X POST "https://xaicreator.com/api/v1/mastodon/publish" \
  -H "Content-Type: application/json" \
  -H "xai-key: your_api_key" \
  -d '{
    "accountUuid": "account_uuid",
    "type": "single",
    "text": "Hello Mastodon!"
  }'

Parameters: Same as Bluesky

Cost: 10 credits

Threads

POST /api/v1/threads/publish

curl -X POST "https://xaicreator.com/api/v1/threads/publish" \
  -H "Content-Type: application/json" \
  -H "xai-key: your_api_key" \
  -d '{
    "accountId": "account_uuid",
    "text": "Hello Threads!",
    "mediaUrls": ["https://example.com/image.jpg"]
  }'

Parameters:

Parameter	Type	Required	Description
`accountId`	`string`	`Yes`	Account UUID
`draftId`	`string`	`No*`	Draft UUID (use draft or text/mediaUrls)
`text`	`string`	`No*`	Post text (max 500 characters)
`mediaUrls`	`array`	`No`	Media URL array
`replyControl`	`string`	`No`	`everyone`, `accounts_you_follow`, `mentioned_only`

Cost: 10 credits

POST /api/v1/linkedin/publish

curl -X POST "https://xaicreator.com/api/v1/linkedin/publish" \
  -H "Content-Type: application/json" \
  -H "xai-key: your_api_key" \
  -d '{
    "accountId": "account_uuid",
    "text": "Hello LinkedIn!",
    "mediaUrls": ["https://example.com/image.jpg"],
    "visibility": "PUBLIC"
  }'

Parameters:

Parameter	Type	Required	Description
`accountId`	`string`	`Yes`	Account UUID
`draftId`	`string`	`No*`	Draft UUID (use draft or text)
`text`	`string`	`No*`	Post text (max 3000 characters)
`mediaUrls`	`array`	`No`	Media URL array
`visibility`	`string`	`No`	`PUBLIC`, `CONNECTIONS`, `LOGGED_IN` (default: `PUBLIC`)

Cost: 10 credits

Scheduled Publishing

Schedule Draft

POST /api/v1/twitter/schedule

curl -X POST "https://xaicreator.com/api/v1/twitter/schedule" \
  -H "Content-Type: application/json" \
  -H "xai-key: your_api_key" \
  -d '{
    "draftId": "draft_uuid",
    "scheduledFor": "2026-01-15T10:00:00Z",
    "targetAccounts": [
      {
        "accountId": "account_id",
        "platform": "twitter"
      }
    ],
    "priority": 0,
    "applyJitter": true
  }'

Parameters:

Parameter	Type	Required	Description
`draftId`	`string`	`Yes`	Draft UUID
`scheduledFor`	`string`	`Yes`	ISO 8601 datetime (UTC)
`targetAccounts`	`array`	`No`	Target accounts (multi-platform)
`accountUuid`	`string`	`No`	Single account (legacy)
`platform`	`string`	`No`	Platform type (default: twitter)
`priority`	`number`	`No`	Priority (default: 0)
`applyJitter`	`boolean`	`No`	Add random jitter ±3min (default: true)

Response:

{
  "message": "Draft scheduled successfully",
  "queueIds": ["uuid1", "uuid2"],
  "scheduledFor": "2026-01-15T10:00:00.000Z",
  "accountCount": 2
}

Cancel Schedule

DELETE /api/v1/twitter/schedule

curl -X DELETE "https://xaicreator.com/api/v1/twitter/schedule?draftId=draft_uuid" \
  -H "xai-key: your_api_key"

List Schedules

GET /api/v1/twitter/schedule

curl "https://xaicreator.com/api/v1/twitter/schedule" \
  -H "xai-key: your_api_key"

Response:

{
  "schedules": [
    {
      "id": "queue_uuid",
      "draftId": "draft_uuid",
      "draftTitle": "My Draft",
      "scheduledFor": "2026-01-15T10:00:00.000Z",
      "priority": 0,
      "attempts": 0,
      "createdAt": "2026-01-14T08:00:00.000Z",
      "platform": "twitter",
      "accountUuid": "account_uuid"
    }
  ]
}

Media Upload

Upload Media

POST /api/v1/twitter/media/upload

curl -X POST "https://xaicreator.com/api/v1/twitter/media/upload" \
  -H "xai-key: your_api_key" \
  -F "files=@/path/to/image.jpg"

Limits:

Maximum 4 files per request
Images: 5MB per file
GIFs: 15MB per file
Videos: 512MB per file

Response:

{
  "code": 0,
  "data": {
    "uploads": [
      {
        "mediaId": "media_id_string",
        "url": "https://pbs.twimg.com/...",
        "type": "image"
      }
    ]
  }
}

GET /api/v1/social-sets

curl "https://xaicreator.com/api/v1/social-sets" \
  -H "xai-key: your_api_key"

Response:

{
  "socialSets": [
    {
      "id": "social-set-id",
      "name": "My Social Set",
      "accounts": [
        {
          "accountId": "account_id",
          "platform": "twitter",
          "username": "username"
        }
      ]
    }
  ]
}

Credits

Check Credits Balance

POST /api/v1/credits

curl -X POST "https://xaicreator.com/api/v1/credits" \
  -H "xai-key: your_api_key"

Response:

{
  "balance": 150,
  "expiresAt": "2026-02-01T00:00:00Z"
}

Error Handling

All endpoints may return errors in this format:

{
  "success": false,
  "error": "ERROR_CODE",
  "message": "Human-readable error message"
}

Common Error Codes

Code	Description
`INVALID_API_KEY`	API key is missing, invalid, or revoked
`USER_NOT_FOUND`	Email not registered
`INVALID_CREDENTIALS`	Invalid email or password
`INSUFFICIENT_CREDITS`	Not enough credits for the operation
`UNAUTHORIZED`	User lacks permission for the resource
`NOT_FOUND`	Requested resource doesn't exist
`RATE_LIMITED`	Too many requests, try again later
`INVALID_INPUT`	Request validation failed
`TOKEN_EXPIRED`	OAuth token has expired (re-auth required)
`OAUTH_NOT_CONFIGURED`	OAuth environment variables not configured

HTTP Status Codes

Status	Description
`200`	Success
`400`	Bad Request (invalid input)
`401`	Unauthorized (invalid API key or token)
`402`	Payment Required (insufficient credits)
`403`	Forbidden (limit exceeded)
`404`	Not Found
`500`	Internal Server Error

Rate Limits

API requests are rate limited per API Key:

Free tier: 100 requests/hour
Pro tier: 1,000 requests/hour
Enterprise: Custom limits

Rate limit headers are included in responses:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 950
X-RateLimit-Reset: 1705272000

Best Practices

Secure Your Keys: Never expose API Keys in client-side code or public repositories
Handle Errors: Always check for error responses and handle appropriately
Check Credits: Verify credit balance before publishing operations
Use Webhooks: For long-running operations, consider setting up webhooks
Cache Responses: Cache Social Set and account data to reduce API calls
Batch Operations: Create threads in a single draft request when possible
Schedule Ahead: Use the scheduling API for optimal posting times
Multi-Platform: Use multi-platform endpoint for simultaneous publishing

Platform Reference

Platform	Max Characters	Max Media	Credit Cost
`Twitter`	280 (or more with Premium)	4 images / 1 video	10
`Bluesky`	300	4 images	10
`Mastodon`	500 (instance-dependent)	4 images	10
`Threads`	500	10 photos / 1 video	10
`LinkedIn`	3000	20 images	10

Support

For API issues or questions:

Email: [email protected]
Documentation: https://xaicreator.com/docs/api
Status Page: https://status.xaicreator.com

API Reference

Overview

Authentication

Getting Your API Key

1. Email Login

2. Google OAuth

3. Twitter OAuth

API Key Management

Get API Keys

Create API Key

Delete API Key

Twitter OAuth 2.0

Initiate Twitter OAuth

Twitter OAuth Callback

Drafts Management

List Drafts

Create Draft

Publishing

Publish to Twitter

Quote Tweet

Multi-Platform Publishing

Platform-Specific Publishing

Bluesky

Mastodon

Threads

LinkedIn

Scheduled Publishing

Schedule Draft

Cancel Schedule

List Schedules

Media Upload

Upload Media

Social Sets

List Social Sets

Credits

Check Credits Balance

Error Handling

Common Error Codes

HTTP Status Codes

Rate Limits

Best Practices

Platform Reference

Support