Script Pilot, inside your tools.
The Script Pilot API lets your own systems create drafts in your brand voice and move the ones you approve wherever they need to go. Nothing posts without your approval.
What it does for you.
Drafts from anywhere
Send a topic from your CMS, a spreadsheet or an automation and get back drafts for each platform, in that brand’s voice.
Your review step stays
Everything arrives as a draft. Approve it through the API, or open Script Pilot and edit it first. You approve every word.
Every client, one system
Agencies can create brands, tune their voice settings and add past posts for each client from their own tools.
Approved posts, where you need them
Pull approved and scheduled posts into your own scheduler, CMS or client reports.
Works with anything that can send an HTTPS request with a header: your own code, or a webhook or HTTP step in automation tools such as Zapier or Make.
How to use it.
Be on Pro or Agency
API access is included with both plans, including the free trial on either. Verify your email address first.
Create a key
In Script Pilot, open API in the sidebar. Name the key after the tool that will use it, choose its permissions and when it expires, then copy it. It is shown once.
Send it with every request
Put the key in the Authorization header as a Bearer token. Every request goes to the same base URL, over HTTPS.
Make your first calls
List your brands to get a brand ID, generate drafts for it, then approve the ones you want.
Base URL
https://scriptpilot.com.au/api/v1Every request
Authorization: Bearer sp_live_…From topic to approved draft
Set SCRIPTPILOT_KEY in your environment first. Never paste a key into code you share.
# 1. Find your brand's ID
curl https://scriptpilot.com.au/api/v1/brands \
-H "Authorization: Bearer $SCRIPTPILOT_KEY"
# 2. Generate three Instagram captions about a topic
curl https://scriptpilot.com.au/api/v1/posts/generate \
-H "Authorization: Bearer $SCRIPTPILOT_KEY" \
-H "Content-Type: application/json" \
-d '{"brand_id": "BRAND_ID", "platforms": ["instagram"],
"content_types": ["caption"], "topic": "Our new winter menu",
"batch_size": 3}'
# 3. Approve the one you like
curl -X POST https://scriptpilot.com.au/api/v1/posts/POST_ID/approve \
-H "Authorization: Bearer $SCRIPTPILOT_KEY"Generating drafts.
POST /posts/generate writes drafts with the same voice settings and checks as the app, and saves them to your account as drafts. The response lists them, each with an id, body, hashtags and guardrail_score. A draft with a serious guardrail issue can’t be approved until it’s fixed.
| Field | What it is |
|---|---|
brand_idRequired | The brand to write for. Get it from GET /brands. |
platformsRequired | One or more of instagram, facebook, linkedin, tiktok, twitter (X). |
content_typesRequired | One or more content types. Each platform takes the types listed in the platform table. |
topicOptional | What the posts are about, up to 500 characters. |
research_briefOptional | Background the drafts should draw on, up to 2,000 characters. |
batch_sizeOptional | Drafts for each platform and content type, 1 to 10. Defaults to 1. |
| Platform | Content types |
|---|---|
Instagraminstagram | captioncarouselreel_scriptstory |
Facebookfacebook | captioncarouselstoryad_copy |
LinkedInlinkedin | captioncarouselthread |
TikToktiktok | reel_scriptcaption |
X (Twitter)twitter | captionthread |
Permissions.
Each key carries only the permissions you give it. A key that only reads posts can’t create or change anything.
- Read brands
brands:read - Read your brands and the status of their voice examples.
- Manage brands
brands:write - Create, update and delete brands, and add voice examples.
- Read posts
posts:read - Read drafts and posts.
- Manage posts
posts:write - Edit, approve, schedule and delete posts.
- Generate drafts
generate - Create new drafts. Each draft counts towards your monthly post allowance.
- Never open to keys
- Your account, password and API keys, billing, connected social accounts, photo and video uploads, analytics. A leaked key can’t change your password, billing or connected accounts.
Endpoint reference.
Paths are relative to https://scriptpilot.com.au/api/v1. Requests and responses are JSON (the file upload is multipart form data), and times are ISO 8601 with a time zone.
Brands
- GET
/brandsList your brands.brands:read - POST
/brandsCreate a brand. Your plan’s brand limit applies.brands:write - GET
/brands/{brand_id}Get one brand, including its voice settings.brands:read - PATCH
/brands/{brand_id}Update a brand’s details, voice dials or platforms.brands:write - DELETE
/brands/{brand_id}Delete a brand and all of its posts.brands:write
Voice examples
- POST
/brands/{brand_id}/corpus/ingestAdd past posts as text, {"kind": "text", "text": …}, or a public link, {"kind": "url", "url": …}. Processed in the background.brands:write - POST
/brands/{brand_id}/corpus/fileUpload a .txt, .pdf or .docx of past posts (up to 10 MB) as the form field file.brands:write - GET
/brands/{brand_id}/corpus/statusSee how many examples are stored and whether processing has finished.brands:read
Drafts and posts
- POST
/posts/generateGenerate drafts for one brand: 1 to 10 for each platform and content type.generate - GET
/postsList posts, newest first. Filter by brand_id, platform or status; page through with page and per_page (up to 100).posts:read - GET
/posts/{post_id}Get one post.posts:read - PATCH
/posts/{post_id}Edit a post’s title, body or hashtags.posts:write - POST
/posts/{post_id}/approveApprove a draft.posts:write - POST
/posts/bulk/approveApprove up to 50 drafts at once. The body is a JSON array of post IDs.posts:write - POST
/posts/{post_id}/schedulePut a post on your calendar at a future time.posts:write - DELETE
/posts/{post_id}Delete a post.posts:write
When something goes wrong.
| Status | What it means |
|---|---|
| 400Can’t be done as asked | For example, approving a post that isn’t a draft, or scheduling a time in the past. |
| 401Key not accepted | The key is missing, mistyped, revoked or expired. |
| 402Plan | Your plan doesn’t include the API, the subscription isn’t active, or this month’s post allowance is used up. |
| 403Not allowed | The key doesn’t have the permission this endpoint needs, or the endpoint isn’t open to keys. |
| 404Not found | It doesn’t exist, or it belongs to another account. Keys only ever see their own account’s data. |
| 422Invalid fields | A field is missing or has the wrong value. The errors list says which. |
Every error has the same shape: a short machine-readable error and a detail written for people.
HTTP/1.1 403 Forbidden
{
"error": "forbidden",
"detail": "API key lacks the 'generate' scope"
}Safe and reliable.
Keep keys on a server
Use keys from your own server or an automation tool’s secret settings, never in a web page, a mobile app or a public code repository.
One key per tool
Give each tool its own key with only the permissions it needs. Revoke a key you no longer use; it stops working straight away.
Allow time to generate
Generating happens while you wait, and a large batch can take a while. Set a generous timeout; 120 seconds is a sensible start.
Check before you retry
If a generate call times out, it may still have finished. List recent drafts with GET /posts?status=draft before trying again, so you don’t create duplicates.
Same allowance as the app
Drafts made through the API count towards your plan’s monthly post allowance, exactly as drafts made in the app do.
Scheduling is planning
Scheduling puts a post on your calendar. Script Pilot posts it for you only where you’ve connected a platform that supports publishing; otherwise it stays on the calendar for you to post, and publish_mode says which.
Coming soon
- Rate-limit headers on every responsesoon
- Safe retries for generate, with an Idempotency-Key headersoon
- Webhooks that tell your system when drafts are readysoon
- A machine-readable OpenAPI filesoon
Questions?
Tell us what you’re connecting and we’ll help you get it working.
support@scriptpilot.com.auAlready on Pro or Agency? Create your key.
Connect your tools.
API access comes with Pro and Agency, including the free trial.
14 days free. No card needed.