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.
- Copy the MCP link below.
- Paste it into your AI tool as a new connector or remote MCP server.
- The tool opens OneCraft in your browser. Sign in.
- Read what the tool asks for, then press Allow.
https://api.onecraft.app/mcpIn Claude Code, run this command:
claude mcp add --transport http onecraft https://api.onecraft.app/mcpWhat 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. Register a client
POST /oauth/registerDo 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. Send the user to the sign-in page
GET /oauth/authorizeMake 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. Exchange the code for tokens
POST /oauth/tokenThe 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=$VERIFIER4. 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. Refresh before the hour ends
POST /oauth/tokenEach 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_ID6. Revoke when you are done
POST /oauth/revokeThis 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
- Proposals, invoices and clients
- Forms and responses
- Slides
- Flyers
- Videos
- Sites
- E-sign
- Social
- Inbox
- Account
Documents
/v1/documents
GET /v1/documentsList your documents
POST /v1/documentsCreate one from a prompt with AI. Answers a job id
POST /v1/documents/blankCreate a blank one, or one from a template
GET /v1/documents/templatesList the templates
POST /v1/documents/filesGet an upload address for a file to send with a create
GET /v1/documents/jobs/:job_idCheck a create, AI edit or export
GET /v1/documents/:idGet one document
PATCH /v1/documents/:idRename it or replace its content
DELETE /v1/documents/:idDelete it
POST /v1/documents/:id/filesGet an upload address for a picture to send with an AI edit
POST /v1/documents/:id/editAsk the AI for a change. Answers a job id
POST /v1/documents/:id/exportExport the PDF
POST /v1/documents/:id/duplicateMake a copy
GET /v1/documents/:id/signing/partiesList the people who sign the document
POST /v1/documents/:id/signing/sendSend it for signingpublish
Proposals, invoices and clients
/v1/proposalsMoney is in whole cents.
Proposals and quotes
GET /v1/proposalsList your proposals and quotes
POST /v1/proposalsCreate one from a prompt with AI. Answers a job id
POST /v1/proposals/blankCreate a blank one, or one from a template
GET /v1/proposals/templatesList the templates
POST /v1/proposals/filesGet an upload address for a file to send with a create
GET /v1/proposals/jobs/:job_idCheck a create, AI edit or export
GET /v1/proposals/:idGet one proposal
PATCH /v1/proposals/:idRename it or replace its content
DELETE /v1/proposals/:idDelete it
GET /v1/proposals/:id/itemsRead its line items
PUT /v1/proposals/:id/itemsReplace its line items
PUT /v1/proposals/:id/pricingSet its pricing
POST /v1/proposals/:id/filesGet an upload address for a picture to send with an AI edit
POST /v1/proposals/:id/editAsk the AI for a change. Answers a job id
POST /v1/proposals/:id/exportExport the PDF
POST /v1/proposals/:id/duplicateMake a copy
POST /v1/proposals/:id/sendSend it to your clientpublish
POST /v1/proposals/:id/resendSend it againpublish
POST /v1/proposals/:id/voidWithdraw a sent proposalpublish
GET /v1/proposals/:id/activityRead what happened after it was sent
POST /v1/proposals/:id/convert-to-invoiceTurn an accepted proposal into an invoice
Invoices
GET /v1/proposals/summaryRead your invoice totals: paid this month, outstanding and overdue
GET /v1/proposals/invoicesList your invoices
POST /v1/proposals/invoicesCreate an invoice
GET /v1/proposals/invoices/:idGet one invoice
PATCH /v1/proposals/invoices/:idChange it
DELETE /v1/proposals/invoices/:idDelete it
POST /v1/proposals/invoices/:id/issueIssue a draft invoice
POST /v1/proposals/invoices/:id/sendSend it to your clientpublish
POST /v1/proposals/invoices/:id/issue-and-sendIssue and send in one steppublish
POST /v1/proposals/invoices/:id/mark-paidMark it paid
POST /v1/proposals/invoices/:id/remind-nowSend a reminder to your clientpublish
POST /v1/proposals/invoices/:id/pay-linkGet the link where your client payspublish
POST /v1/proposals/invoices/:id/voidVoid it
POST /v1/proposals/invoices/:id/exportExport the PDF
Clients
GET /v1/proposals/clientsList your clients
POST /v1/proposals/clientsAdd a client
GET /v1/proposals/clients/:idGet one client
PATCH /v1/proposals/clients/:idChange a client
DELETE /v1/proposals/clients/:idRemove 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/formsList your forms
POST /v1/formsCreate one from a prompt with AI. Answers a job id
POST /v1/forms/blankCreate a blank one, or one from a template
GET /v1/forms/templatesList the templates
POST /v1/forms/filesGet an upload address for a file to send with a create
GET /v1/forms/jobs/:job_idCheck a create, AI edit or export
GET /v1/forms/:idGet one form
PATCH /v1/forms/:idRename it or replace its content
DELETE /v1/forms/:idDelete it
POST /v1/forms/:id/editAsk the AI for a change. Answers a job id
POST /v1/forms/:id/filesGet an upload address for a picture to send with an AI edit
POST /v1/forms/:id/publishPublish the draftpublish
POST /v1/forms/:id/unpublishTake the link downpublish
POST /v1/forms/:id/disableSwitch it off
POST /v1/forms/:id/enableSwitch it on again
POST /v1/forms/:id/duplicateMake a copy
POST /v1/forms/:id/exportExport the PDF or the fillable PDF
Responses
GET /v1/forms/:id/responsesList the responses
GET /v1/forms/:id/responses/:response_idRead one response
DELETE /v1/forms/:id/responses/:response_idDelete a response
POST /v1/forms/:id/responses/:response_id/exportExport a response as PDF
Slides
/v1/slidesThe slides keep filling in for a short while after the job is ready.
GET /v1/slidesList your presentations
POST /v1/slidesCreate one from a prompt with AI. Answers a job id
POST /v1/slides/filesGet an upload address for a file to send with a create
GET /v1/slides/jobs/:job_idCheck a create, AI edit or export
GET /v1/slides/:idGet one presentation
PATCH /v1/slides/:idRename it or replace its content
DELETE /v1/slides/:idDelete it
POST /v1/slides/:id/filesGet an upload address for a picture to send with an AI edit
POST /v1/slides/:id/editAsk the AI for a change. Answers a job id
POST /v1/slides/:id/exportExport it as PDF or PowerPoint
POST /v1/slides/:id/duplicateMake a copy
POST /v1/slides/:id/disableSwitch it off
POST /v1/slides/:id/enableSwitch it on again
Flyers
/v1/flyersFlyers and posters.
GET /v1/flyersList your flyers
POST /v1/flyersCreate one from a prompt with AI. Answers a job id
POST /v1/flyers/filesGet an upload address for a file to send with a create
GET /v1/flyers/jobs/:job_idCheck a create, AI edit or export
GET /v1/flyers/:idGet one flyer
PATCH /v1/flyers/:idRename it or replace its content
DELETE /v1/flyers/:idDelete it
POST /v1/flyers/:id/filesGet an upload address for a picture to send with an AI edit
POST /v1/flyers/:id/editAsk the AI for a change. Answers a job id
POST /v1/flyers/:id/exportExport it as PNG, JPEG or PDF
POST /v1/flyers/:id/duplicateMake a copy
POST /v1/flyers/:id/disableSwitch it off
POST /v1/flyers/:id/enableSwitch it on again
Videos
/v1/videos
GET /v1/videosList your videos
POST /v1/videosCreate one from a prompt with AI. Answers a job id
POST /v1/videos/blankCreate a blank one
GET /v1/videos/jobs/:job_idCheck a create, AI edit or export
GET /v1/videos/:idGet one video
PATCH /v1/videos/:idRename it or replace its content
DELETE /v1/videos/:idDelete it
POST /v1/videos/:id/filesGet an upload address for a picture or clip for the video
POST /v1/videos/:id/editAsk the AI for a change. Answers a job id
POST /v1/videos/:id/exportExport the MP4
POST /v1/videos/:id/shareTurn the watch link on or offpublish
POST /v1/videos/:id/disableSwitch it off
POST /v1/videos/:id/enableSwitch it on again
Sites
/v1/sitesWebsites and phone apps. Only websites can be published.
GET /v1/sitesList your sites and apps
POST /v1/sitesCreate a website or app from a prompt with AI. Answers a job id
GET /v1/sites/jobs/:job_idCheck a create or AI edit
GET /v1/sites/:idGet one site
PATCH /v1/sites/:idRename it, set its address or change its settings
DELETE /v1/sites/:idDelete it
GET /v1/sites/:id/slug-checkCheck if an address is free
POST /v1/sites/:id/editAsk the AI for a change. Answers a job id
GET /v1/sites/:id/filesList the project files
POST /v1/sites/:id/filesGet an upload address for a picture to send with an AI edit
GET /v1/sites/:id/files/contentRead one project file
GET /v1/sites/:id/commitsRead the history
GET /v1/sites/:id/buildRead the build status
POST /v1/sites/:id/rebuildBuild it again
POST /v1/sites/:id/restoreGo back to an earlier commit
POST /v1/sites/:id/exportDownload the project as a zip
GET /v1/sites/:id/appRead the project page of an app
GET /v1/sites/:id/versionsList the published versions
GET /v1/sites/:id/versions/:version_idGet one version
POST /v1/sites/:id/publishPublish the websitepublish
POST /v1/sites/:id/unpublishTake it offlinepublish
POST /v1/sites/:id/rollbackGo back to an earlier published versionpublish
GET /v1/sites/:id/statsRead the visit stats
E-sign
/v1/esignOne PDF for each envelope. Only a draft can be changed or deleted.
GET /v1/esign/envelopesList your envelopes
POST /v1/esign/envelopesCreate a draft
GET /v1/esign/envelopes/:idGet one, with who has signed and the signed PDF links
PATCH /v1/esign/envelopes/:idChange a draft
DELETE /v1/esign/envelopes/:idDelete a draft
POST /v1/esign/envelopes/:id/filesGet an upload address for the PDF
POST /v1/esign/envelopes/:id/documentConfirm the uploaded PDF
PUT /v1/esign/envelopes/:id/recipients-and-fieldsSet the recipients and their fields
POST /v1/esign/envelopes/:id/sendSend it for signingpublish
POST /v1/esign/envelopes/:id/voidWithdraw a sent envelopepublish
POST /v1/esign/envelopes/:id/recipients/:recipient_id/resendSend the invitation to a signer againpublish
Inbox
/v1/inboxCustomer mail, business files and business memory.
Messages
GET /v1/inbox/messagesList your messages
GET /v1/inbox/messages/summaryCount the messages that wait for you
GET /v1/inbox/messages/:idRead one message with its reply draft
POST /v1/inbox/messages/:id/sendSend the replypublish
POST /v1/inbox/messages/:id/redraftAsk for a new draft
POST /v1/inbox/messages/:id/dismissDismiss the message
Business files
GET /v1/inbox/filesList your files and folders
POST /v1/inbox/filesGet an upload address for a new file
POST /v1/inbox/files/:id/completeConfirm the upload
GET /v1/inbox/files/:id/urlGet a download link
PATCH /v1/inbox/files/:idRename or move a file
DELETE /v1/inbox/files/:idDelete a file
POST /v1/inbox/files/foldersCreate a folder
PATCH /v1/inbox/files/folders/:idRename a folder
DELETE /v1/inbox/files/folders/:idDelete a folder
Business memory and questions
GET /v1/inbox/memoryRead your business memory
POST /v1/inbox/memory/factsAdd a fact
DELETE /v1/inbox/memory/facts/:idRemove a fact
GET /v1/inbox/questionsList the questions you asked
POST /v1/inbox/questionsAsk a question about your business
Account
/v1/account
GET /v1/accountRead 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_KEY401The access token is missing, wrong, expired or revoked.
MISSING_SCOPE403The token does not have the permission this operation needs.
RATE_LIMITED429Too many requests for this token. Try again in a minute.
INSUFFICIENT_CREDITS402You have no credits left on your plan.
PAID_FEATURE402This needs a paid plan.
STORAGE_LIMIT402Your plan storage is full.
PAYMENT_REQUIRED402Another plan or credit refusal.
NOT_FOUND404The item or address does not exist, or the item belongs to someone else.
VALIDATION400The request is not valid. The message says what to fix.