Skip to content
PaximalDevelopersOpen Paximal
GUIDE · API v1

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.

1

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.

POST/api/v1/projects
cURL
curl -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
JSON
{
  "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"
  }
}
2

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
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 ↗

3

Submit the project

Use the project_id from step 1 as PROJECT_ID. No request body needed.

POST/api/v1/projects/{project_id}/submit
cURL
curl -X POST \
  "https://next.paximal.com/api/v1/projects/$PROJECT_ID/submit" \
  -H "Authorization: Bearer $PAXIMAL_API_KEY"
You’re ready.

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
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_referencestring

A reference unique to your account. Generated when omitted. 1–100 characters; no slashes or control characters. Case-insensitive after trimming.

invention_namestring

Working title of the invention. Up to 200 characters.

descriptionstring

Background and description of the idea. Up to 20,000 characters.

inventorsstring[]

Inventor names. Up to 20 names, 200 characters each.

entity_namestring

Company or individual associated with the project. Up to 200 characters.

entity_typestring

Either "company" or "individual".

external_idstring

Your 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.