oneCraft

OneCraft for developers

Connect an AI tool to your OneCraft account with one link, or call the API from your own code. Both use a sign-in. Both follow your plan and use your credits, the same as the app.

Connect an AI tool

This works with Claude, Cursor and other tools that support MCP. There is nothing to install.

  1. Copy the MCP link below.
  2. Paste it into your AI tool as a new connector or remote MCP server.
  3. The tool opens OneCraft in your browser. Sign in.
  4. Read what the tool asks for, then press Allow.
https://api.onecraft.app/mcp

In Claude Code, run this command:

claude mcp add --transport http onecraft https://api.onecraft.app/mcp

What the permissions mean

See your items

Scope read

The tool can list and read your items, check jobs and export files.

Create and change your items

Scope write

The tool can make new items and edit, copy or delete the ones you have.

Publish, send and post for you

Scope publish

The tool can publish a site or form, send to your customers and post to your channels. You see this line only when the tool asks for it.

Remove a connected app

Open Settings, API, Connected apps in OneCraft. Press Remove next to the app and confirm. The app stops working at once. An app you do not use for 30 days is removed for you.

Use the API from your own code

The base address is https://api.onecraft.app/v1. Your script signs in the same way an AI tool does, with OAuth 2.1 and PKCE. The user approves it in the browser and your script gets an access token.

  1. 1. Register a client

    POST /oauth/register

    Do this once. Keep the client_id from the answer. There is no client secret.

    curl -X POST https://api.onecraft.app/oauth/register \
      -H "Content-Type: application/json" \
      -d '{"client_name": "My script", "redirect_uris": ["http://localhost:8123/callback"]}'
  2. 2. Send the user to the sign-in page

    GET /oauth/authorize

    Make a random code verifier and its challenge (PKCE, S256). Open the address in a browser. The user signs in and presses Allow. The browser returns to your address with a code. Add publish to scope only if you need to send, publish or post.

    VERIFIER=$(openssl rand -base64 60 | tr -d '\n=+/' | cut -c1-64)
    CHALLENGE=$(printf '%s' "$VERIFIER" | openssl dgst -sha256 -binary | openssl base64 | tr '+/' '-_' | tr -d '=')
    
    open "https://api.onecraft.app/oauth/authorize?response_type=code&client_id=$CLIENT_ID&redirect_uri=http://localhost:8123/callback&code_challenge=$CHALLENGE&code_challenge_method=S256&scope=read%20write&state=abc123"
  3. 3. Exchange the code for tokens

    POST /oauth/token

    The code works once and lasts 5 minutes. The answer holds an access token (1 hour) and a refresh token (30 days).

    curl -X POST https://api.onecraft.app/oauth/token \
      -d grant_type=authorization_code \
      -d code=$CODE \
      -d client_id=$CLIENT_ID \
      -d redirect_uri=http://localhost:8123/callback \
      -d code_verifier=$VERIFIER
  4. 4. Call the API

    Authorization: Bearer <access token>

    Send the access token on every request.

    curl https://api.onecraft.app/v1/documents \
      -H "Authorization: Bearer $ACCESS_TOKEN"
  5. 5. Refresh before the hour ends

    POST /oauth/token

    Each refresh gives a new access token and a new refresh token. Keep the new refresh token. The old one stops working.

    curl -X POST https://api.onecraft.app/oauth/token \
      -d grant_type=refresh_token \
      -d refresh_token=$REFRESH_TOKEN \
      -d client_id=$CLIENT_ID
  6. 6. Revoke when you are done

    POST /oauth/revoke

    This ends the connection and its tokens.

    curl -X POST https://api.onecraft.app/oauth/revoke \
      -d token=$REFRESH_TOKEN \
      -d client_id=$CLIENT_ID

How work is returned

A success is { "data": ... }. A list holds items and next_cursor.

Jobs

A create and an AI edit take time, so they answer with a job id. Ask GET /v1/<module>/jobs/<job id> until the status is ready. The status is pending while the work runs and failed when it could not be done. A ready job gives the item's id and a url that opens it in the builder.

# Start the work
curl -X POST https://api.onecraft.app/v1/documents \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "A one page welcome letter for new customers"}'
# {"data": {"job_id": "gen_123", "status": "pending"}}

# Ask until the status is ready
curl https://api.onecraft.app/v1/documents/jobs/gen_123 \
  -H "Authorization: Bearer $ACCESS_TOKEN"
# {"data": {"status": "ready", "id": "<item id>", "url": "<builder link>"}}

An export answers with a download link in url when the file is ready. When the file is still being made it answers with a job id, and the ready job holds the link.

Send a picture with an edit

Ask POST /v1/<module>/<id>/files for an upload address. Upload the picture to the returned address. Then pass the returned file in files of the edit. Most modules take up to 4 pictures in one edit.

# 1. Ask for an upload address
curl -X POST https://api.onecraft.app/v1/documents/$ID/files \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"filename": "cover.png", "content_type": "image/png", "size_bytes": 48211}'
# {"data": {"file": {"file_id": "..."}, "upload_url": "...", "upload_method": "PUT", "upload_headers": {"Content-Type": "image/png"}}}

# 2. Send the bytes to upload_url (no Authorization header here)
curl -X PUT "$UPLOAD_URL" -H "Content-Type: image/png" --data-binary @cover.png

# 3. Pass the file in files
curl -X POST https://api.onecraft.app/v1/documents/$ID/edit \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message": "Use this as the cover picture", "files": [{"file_id": "..."}]}'

What you can do

Every path below comes after https://api.onecraft.app. An operation marked publish needs the publish permission. All others need only read or write.

Documents

/v1/documents

  • GET /v1/documents

    List your documents

  • POST /v1/documents

    Create one from a prompt with AI. Answers a job id

  • POST /v1/documents/blank

    Create a blank one, or one from a template

  • GET /v1/documents/templates

    List the templates

  • POST /v1/documents/files

    Get an upload address for a file to send with a create

  • GET /v1/documents/jobs/:job_id

    Check a create, AI edit or export

  • GET /v1/documents/:id

    Get one document

  • PATCH /v1/documents/:id

    Rename it or replace its content

  • DELETE /v1/documents/:id

    Delete it

  • POST /v1/documents/:id/files

    Get an upload address for a picture to send with an AI edit

  • POST /v1/documents/:id/edit

    Ask the AI for a change. Answers a job id

  • POST /v1/documents/:id/export

    Export the PDF

  • POST /v1/documents/:id/duplicate

    Make a copy

  • GET /v1/documents/:id/signing/parties

    List the people who sign the document

  • POST /v1/documents/:id/signing/send

    Send it for signingpublish

Proposals, invoices and clients

/v1/proposalsMoney is in whole cents.

Proposals and quotes

  • GET /v1/proposals

    List your proposals and quotes

  • POST /v1/proposals

    Create one from a prompt with AI. Answers a job id

  • POST /v1/proposals/blank

    Create a blank one, or one from a template

  • GET /v1/proposals/templates

    List the templates

  • POST /v1/proposals/files

    Get an upload address for a file to send with a create

  • GET /v1/proposals/jobs/:job_id

    Check a create, AI edit or export

  • GET /v1/proposals/:id

    Get one proposal

  • PATCH /v1/proposals/:id

    Rename it or replace its content

  • DELETE /v1/proposals/:id

    Delete it

  • GET /v1/proposals/:id/items

    Read its line items

  • PUT /v1/proposals/:id/items

    Replace its line items

  • PUT /v1/proposals/:id/pricing

    Set its pricing

  • POST /v1/proposals/:id/files

    Get an upload address for a picture to send with an AI edit

  • POST /v1/proposals/:id/edit

    Ask the AI for a change. Answers a job id

  • POST /v1/proposals/:id/export

    Export the PDF

  • POST /v1/proposals/:id/duplicate

    Make a copy

  • POST /v1/proposals/:id/send

    Send it to your clientpublish

  • POST /v1/proposals/:id/resend

    Send it againpublish

  • POST /v1/proposals/:id/void

    Withdraw a sent proposalpublish

  • GET /v1/proposals/:id/activity

    Read what happened after it was sent

  • POST /v1/proposals/:id/convert-to-invoice

    Turn an accepted proposal into an invoice

Invoices

  • GET /v1/proposals/summary

    Read your invoice totals: paid this month, outstanding and overdue

  • GET /v1/proposals/invoices

    List your invoices

  • POST /v1/proposals/invoices

    Create an invoice

  • GET /v1/proposals/invoices/:id

    Get one invoice

  • PATCH /v1/proposals/invoices/:id

    Change it

  • DELETE /v1/proposals/invoices/:id

    Delete it

  • POST /v1/proposals/invoices/:id/issue

    Issue a draft invoice

  • POST /v1/proposals/invoices/:id/send

    Send it to your clientpublish

  • POST /v1/proposals/invoices/:id/issue-and-send

    Issue and send in one steppublish

  • POST /v1/proposals/invoices/:id/mark-paid

    Mark it paid

  • POST /v1/proposals/invoices/:id/remind-now

    Send a reminder to your clientpublish

  • POST /v1/proposals/invoices/:id/pay-link

    Get the link where your client payspublish

  • POST /v1/proposals/invoices/:id/void

    Void it

  • POST /v1/proposals/invoices/:id/export

    Export the PDF

Clients

  • GET /v1/proposals/clients

    List your clients

  • POST /v1/proposals/clients

    Add a client

  • GET /v1/proposals/clients/:id

    Get one client

  • PATCH /v1/proposals/clients/:id

    Change a client

  • DELETE /v1/proposals/clients/:id

    Remove a client

Forms and responses

/v1/formsClassic and conversational forms both work. A change to the draft reaches visitors when you publish again.

Forms

  • GET /v1/forms

    List your forms

  • POST /v1/forms

    Create one from a prompt with AI. Answers a job id

  • POST /v1/forms/blank

    Create a blank one, or one from a template

  • GET /v1/forms/templates

    List the templates

  • POST /v1/forms/files

    Get an upload address for a file to send with a create

  • GET /v1/forms/jobs/:job_id

    Check a create, AI edit or export

  • GET /v1/forms/:id

    Get one form

  • PATCH /v1/forms/:id

    Rename it or replace its content

  • DELETE /v1/forms/:id

    Delete it

  • POST /v1/forms/:id/edit

    Ask the AI for a change. Answers a job id

  • POST /v1/forms/:id/files

    Get an upload address for a picture to send with an AI edit

  • POST /v1/forms/:id/publish

    Publish the draftpublish

  • POST /v1/forms/:id/unpublish

    Take the link downpublish

  • POST /v1/forms/:id/disable

    Switch it off

  • POST /v1/forms/:id/enable

    Switch it on again

  • POST /v1/forms/:id/duplicate

    Make a copy

  • POST /v1/forms/:id/export

    Export the PDF or the fillable PDF

Responses

  • GET /v1/forms/:id/responses

    List the responses

  • GET /v1/forms/:id/responses/:response_id

    Read one response

  • DELETE /v1/forms/:id/responses/:response_id

    Delete a response

  • POST /v1/forms/:id/responses/:response_id/export

    Export a response as PDF

Slides

/v1/slidesThe slides keep filling in for a short while after the job is ready.

  • GET /v1/slides

    List your presentations

  • POST /v1/slides

    Create one from a prompt with AI. Answers a job id

  • POST /v1/slides/files

    Get an upload address for a file to send with a create

  • GET /v1/slides/jobs/:job_id

    Check a create, AI edit or export

  • GET /v1/slides/:id

    Get one presentation

  • PATCH /v1/slides/:id

    Rename it or replace its content

  • DELETE /v1/slides/:id

    Delete it

  • POST /v1/slides/:id/files

    Get an upload address for a picture to send with an AI edit

  • POST /v1/slides/:id/edit

    Ask the AI for a change. Answers a job id

  • POST /v1/slides/:id/export

    Export it as PDF or PowerPoint

  • POST /v1/slides/:id/duplicate

    Make a copy

  • POST /v1/slides/:id/disable

    Switch it off

  • POST /v1/slides/:id/enable

    Switch it on again

Flyers

/v1/flyersFlyers and posters.

  • GET /v1/flyers

    List your flyers

  • POST /v1/flyers

    Create one from a prompt with AI. Answers a job id

  • POST /v1/flyers/files

    Get an upload address for a file to send with a create

  • GET /v1/flyers/jobs/:job_id

    Check a create, AI edit or export

  • GET /v1/flyers/:id

    Get one flyer

  • PATCH /v1/flyers/:id

    Rename it or replace its content

  • DELETE /v1/flyers/:id

    Delete it

  • POST /v1/flyers/:id/files

    Get an upload address for a picture to send with an AI edit

  • POST /v1/flyers/:id/edit

    Ask the AI for a change. Answers a job id

  • POST /v1/flyers/:id/export

    Export it as PNG, JPEG or PDF

  • POST /v1/flyers/:id/duplicate

    Make a copy

  • POST /v1/flyers/:id/disable

    Switch it off

  • POST /v1/flyers/:id/enable

    Switch it on again

Videos

/v1/videos

  • GET /v1/videos

    List your videos

  • POST /v1/videos

    Create one from a prompt with AI. Answers a job id

  • POST /v1/videos/blank

    Create a blank one

  • GET /v1/videos/jobs/:job_id

    Check a create, AI edit or export

  • GET /v1/videos/:id

    Get one video

  • PATCH /v1/videos/:id

    Rename it or replace its content

  • DELETE /v1/videos/:id

    Delete it

  • POST /v1/videos/:id/files

    Get an upload address for a picture or clip for the video

  • POST /v1/videos/:id/edit

    Ask the AI for a change. Answers a job id

  • POST /v1/videos/:id/export

    Export the MP4

  • POST /v1/videos/:id/share

    Turn the watch link on or offpublish

  • POST /v1/videos/:id/disable

    Switch it off

  • POST /v1/videos/:id/enable

    Switch it on again

Sites

/v1/sitesWebsites and phone apps. Only websites can be published.

  • GET /v1/sites

    List your sites and apps

  • POST /v1/sites

    Create a website or app from a prompt with AI. Answers a job id

  • GET /v1/sites/jobs/:job_id

    Check a create or AI edit

  • GET /v1/sites/:id

    Get one site

  • PATCH /v1/sites/:id

    Rename it, set its address or change its settings

  • DELETE /v1/sites/:id

    Delete it

  • GET /v1/sites/:id/slug-check

    Check if an address is free

  • POST /v1/sites/:id/edit

    Ask the AI for a change. Answers a job id

  • GET /v1/sites/:id/files

    List the project files

  • POST /v1/sites/:id/files

    Get an upload address for a picture to send with an AI edit

  • GET /v1/sites/:id/files/content

    Read one project file

  • GET /v1/sites/:id/commits

    Read the history

  • GET /v1/sites/:id/build

    Read the build status

  • POST /v1/sites/:id/rebuild

    Build it again

  • POST /v1/sites/:id/restore

    Go back to an earlier commit

  • POST /v1/sites/:id/export

    Download the project as a zip

  • GET /v1/sites/:id/app

    Read the project page of an app

  • GET /v1/sites/:id/versions

    List the published versions

  • GET /v1/sites/:id/versions/:version_id

    Get one version

  • POST /v1/sites/:id/publish

    Publish the websitepublish

  • POST /v1/sites/:id/unpublish

    Take it offlinepublish

  • POST /v1/sites/:id/rollback

    Go back to an earlier published versionpublish

  • GET /v1/sites/:id/stats

    Read the visit stats

E-sign

/v1/esignOne PDF for each envelope. Only a draft can be changed or deleted.

  • GET /v1/esign/envelopes

    List your envelopes

  • POST /v1/esign/envelopes

    Create a draft

  • GET /v1/esign/envelopes/:id

    Get one, with who has signed and the signed PDF links

  • PATCH /v1/esign/envelopes/:id

    Change a draft

  • DELETE /v1/esign/envelopes/:id

    Delete a draft

  • POST /v1/esign/envelopes/:id/files

    Get an upload address for the PDF

  • POST /v1/esign/envelopes/:id/document

    Confirm the uploaded PDF

  • PUT /v1/esign/envelopes/:id/recipients-and-fields

    Set the recipients and their fields

  • POST /v1/esign/envelopes/:id/send

    Send it for signingpublish

  • POST /v1/esign/envelopes/:id/void

    Withdraw a sent envelopepublish

  • POST /v1/esign/envelopes/:id/recipients/:recipient_id/resend

    Send the invitation to a signer againpublish

Social

/v1/socialConnect and remove channels in the app.

  • GET /v1/social/connections

    List your connected channels

  • GET /v1/social/posts

    List your posts

  • POST /v1/social/posts

    Post a video or flyer now, at a set time, or on a repeatpublish

  • GET /v1/social/posts/recurring

    List your repeats

  • POST /v1/social/posts/recurring/:id/stop

    Stop a repeat

  • POST /v1/social/posts/:id/cancel

    Cancel a scheduled post

  • POST /v1/social/posts/:id/retry

    Try a failed post againpublish

  • POST /v1/social/captions/suggest

    Have a caption written for you

Inbox

/v1/inboxCustomer mail, business files and business memory.

Messages

  • GET /v1/inbox/messages

    List your messages

  • GET /v1/inbox/messages/summary

    Count the messages that wait for you

  • GET /v1/inbox/messages/:id

    Read one message with its reply draft

  • POST /v1/inbox/messages/:id/send

    Send the replypublish

  • POST /v1/inbox/messages/:id/redraft

    Ask for a new draft

  • POST /v1/inbox/messages/:id/dismiss

    Dismiss the message

Business files

  • GET /v1/inbox/files

    List your files and folders

  • POST /v1/inbox/files

    Get an upload address for a new file

  • POST /v1/inbox/files/:id/complete

    Confirm the upload

  • GET /v1/inbox/files/:id/url

    Get a download link

  • PATCH /v1/inbox/files/:id

    Rename or move a file

  • DELETE /v1/inbox/files/:id

    Delete a file

  • POST /v1/inbox/files/folders

    Create a folder

  • PATCH /v1/inbox/files/folders/:id

    Rename a folder

  • DELETE /v1/inbox/files/folders/:id

    Delete a folder

Business memory and questions

  • GET /v1/inbox/memory

    Read your business memory

  • POST /v1/inbox/memory/facts

    Add a fact

  • DELETE /v1/inbox/memory/facts/:id

    Remove a fact

  • GET /v1/inbox/questions

    List the questions you asked

  • POST /v1/inbox/questions

    Ask a question about your business

Account

/v1/account

  • GET /v1/account

    Read your plan and the credits you have left

Rules and limits

  • The API follows the same credits and plan rules as the app. Paid work uses your credits.
  • Each access token may send 60 requests a minute. Within those, it may start AI work 10 times a minute.
  • An access token lasts 1 hour. A refresh token lasts 30 days from its last use.
  • You only reach your own items. An item of another owner answers 404, the same as one that does not exist.

Errors

Every failure has the same shape: { error: { code, message } }.

{
  "error": {
    "code": "MISSING_SCOPE",
    "message": "This access token does not have the publish scope",
    "scope": "publish"
  }
}
  • INVALID_KEY 401

    The access token is missing, wrong, expired or revoked.

  • MISSING_SCOPE 403

    The token does not have the permission this operation needs.

  • RATE_LIMITED 429

    Too many requests for this token. Try again in a minute.

  • INSUFFICIENT_CREDITS 402

    You have no credits left on your plan.

  • PAID_FEATURE 402

    This needs a paid plan.

  • STORAGE_LIMIT 402

    Your plan storage is full.

  • PAYMENT_REQUIRED 402

    Another plan or credit refusal.

  • NOT_FOUND 404

    The item or address does not exist, or the item belongs to someone else.

  • VALIDATION 400

    The request is not valid. The message says what to fix.