Submit projects to Paximal via the API
Create a project in a Paximal account or organization, upload your documents, and mark it ready for progression.
Create a project
Use an API key belonging to the destination Paximal account. For an organization, use that account’s key configured for the destination organization. Set it as PAXIMAL_API_KEY below.
No request body is required. Paximal generates a reference and prepares the project for IDF generation. The patent attorney chooses the patent agent later in Paximal.
/api/v1/projectscurl -X POST https://next.paximal.com/api/v1/projects \
-H "Authorization: Bearer $PAXIMAL_API_KEY"
Save the returned project_id. The upload object contains everything you need to send files directly to Box.
Example response 201 Created
{
"project_id": "…",
"project_reference": "PX-7F2A81C09B34",
"status": "draft",
"upload": {
"url": "https://upload.box.com/api/2.0/files/content",
"token": "…",
"folder_id": "…",
"expires_at": "2026-10-13T18:00:00.000Z"
}
}
Upload your documents Optional
Use upload.url, upload.token, and upload.folder_id from the response as the three Box variables below. Repeat for each file.
curl "$BOX_UPLOAD_URL" \
-H "Authorization: Bearer $BOX_UPLOAD_TOKEN" \
-F "attributes={\"name\":\"disclosure.pdf\",\"parent\":{\"id\":\"$BOX_FOLDER_ID\"}}" \
-F "file=@disclosure.pdf"
Send the attributes before the file. Use the returned Box token for this request. Keep your Paximal API key for Paximal requests. Wait for Box to confirm each upload before submitting. Box upload documentation ↗
Submit the project
Use the project_id from step 1 as PROJECT_ID. No request body needed.
/api/v1/projects/{project_id}/submitcurl -X POST \
"https://next.paximal.com/api/v1/projects/$PROJECT_ID/submit" \
-H "Authorization: Bearer $PAXIMAL_API_KEY"
The response returns status: "ready". Your uploaded documents are ready for IDF generation.
Submit records readiness only. It does not start an agent or consume credits. Repeating submit is safe.
Add more context
Every field is optional. To include any, add a JSON body and Content-Type: application/json to your create request.
Example with project details JSON
{
"project_reference": "IDEA-0042",
"invention_name": "Adaptive cooling controller",
"description": "The invention adjusts cooling based on…",
"inventors": ["Alex Morgan", "Sam Chen"],
"entity_name": "Acme Labs",
"entity_type": "company",
"external_id": "discovery-0042"
}
project_referencestringA reference unique to your account. Generated when omitted. 1–100 characters; no slashes or control characters. Case-insensitive after trimming.
invention_namestringWorking title of the invention. Up to 200 characters.
descriptionstringBackground and description of the idea. Up to 20,000 characters.
inventorsstring[]Inventor names. Up to 20 names, 200 characters each.
entity_namestringCompany or individual associated with the project. Up to 200 characters.
entity_typestringEither "company" or "individual".
external_idstringYour system’s identifier for this idea. Up to 200 characters; not a unique key.
A few useful details
What if my reference already exists?
Create returns 409 project_reference_exists. The error includes the existing project ID when available. References are compared case-insensitively within the API-key owner’s account. No idempotency header is needed.
What if the upload token expires or a request times out?
For an existing draft, GET /api/v1/projects/{project_id} with your Paximal API key returns fresh upload credentials for the same folder. After a create timeout, check your projects before retrying: a create without a reference always creates a new project. A Box filename conflict does not confirm identical contents; check the file before submitting.
Which files can I upload?
Uploads go directly to Box and follow your Box account’s size and storage limits. Use DOCX, PDF, TXT, Markdown, or PNG for Paximal source material. Intake stores documents without processing them; each agent’s input requirements apply when you run it later.
How do authentication and readiness work?
Your configured user API key needs projects:write for create, submit, and recovery. Paximal and Box setup must be complete. A submitted project stays in the normal workspace; readiness does not lock its files. Previously issued Box tokens remain usable until they expire.
Other errors
400 invalid fields · 401 invalid key · 403 missing permissions · 404 project not found · 429 rate limit (follow Retry-After) · 503 intake disabled, IDF generation unavailable, or temporary service failure.
