Customer API and webhooks

One request flow

Use https://api.messypoly.com as the API base URL. The normal model flow is: create an import, upload the bytes to the returned presigned URL, mark the import complete, queue an action, poll the job, then fetch artifact URLs.

export MESSYPOLY_API_URL=https://api.messypoly.com
export MESSYPOLY_API_KEY=mpk_…

# A complete working example is also available in examples/node/import-and-optimize.mjs
node examples/node/import-and-optimize.mjs ./model.glb

Authentication, scopes, and idempotency

Create a key in the workspace account menu under Developer settings. Send it on every request:

Authorization: Bearer mpk_…

curl -X POST "$MESSYPOLY_API_URL/api/v1/imports" \
  -H "Authorization: Bearer $MESSYPOLY_API_KEY" \
  -H "Idempotency-Key: import-$(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"filename":"model.glb","sizeBytes":123456,"contentType":"model/gltf-binary"}'

Import lifecycle

1. POST /api/v1/imports with filename, sizeBytes, and optional contentType/sha256. Save the import id and upload URL.
2. Upload the exact bytes with PUT to that presigned URL. Do not send the bearer token to object storage.
3. POST /api/v1/imports/:importId/complete after the upload succeeds.
4. Use GET /api/v1/imports/:importId to inspect upload readiness without starting work.
5. Queue an import action. Use generate for an image import; use inspect or optimize for a model import.
6. Poll GET /api/v1/jobs/:jobId, or subscribe to terminal webhooks, until the job is terminal.

const imported = await api('POST', '/api/v1/imports', {
  filename: 'model.glb', sizeBytes, contentType: 'model/gltf-binary'
});
await fetch(imported.upload.url, { method: 'PUT',
  headers: { 'content-type': 'model/gltf-binary' }, body: bytes });
await api('POST', `/api/v1/imports/${imported.id}/complete`);
const queued = await api('POST', `/api/v1/imports/${imported.id}/actions`, {
  action: 'optimize', intent: 'realistic'
});
const job = await api('GET', `/api/v1/jobs/${queued.jobId}`);

Import status is pending_upload, ready, processing, or terminal. A missing object is retryable; it is not treated as a rejected import until source validation definitively fails.

Every action and its credit cost

Action requests go to POST /api/v1/imports/:importId/actions for intake, or POST /api/v1/versions/:versionId/actions for a retained model version. Put the action-specific object at the top level shown below. Costs are economy-v2 and are reserved when a paid job is accepted.

Action request examples

All examples below are bodies for the action endpoint. The exact JSON Schema, including bounds and required fields, is authoritative in the OpenAPI spec.

{
  "action": "optimize",
  "intent": "custom",
  "custom": {
    "targetTriangleCount": 50000,
    "maxTextureSize": 2048,
    "simplifyErrorBudget": 0.02
  }
}

{
  "action": "resize",
  "resize": {
    "target": {"kind":"dimension","axis":"z","value":120,"unit":"mm"},
    "origin": "bottom-center",
    "ground": true
  }
}

{
  "action": "hollow",
  "hollow": {
    "wallThicknessMm": 2,
    "drainHoleDiameterMm": 4,
    "drainPositionPercent": [50, 5],
    "drainDirection": "bottom"
  }
}

{
  "action": "split",
  "split": {
    "axis": "z",
    "positionPercent": 50,
    "connectorMode": "peg-and-socket",
    "layoutMode": "separated",
    "maximumPartCount": 2
  }
}

{"action":"appearance","appearance":{"operation":"material","patches":[{"materialIndex":0,"roughnessFactor":0.55,"metallicFactor":0.1}]}}

Resources and management endpoints

Jobs, cancellation, and artifacts

Terminal statuses include COMPLETE, FAILED, CANCELED, EXPIRED, NO_SAFE_RESULT, and REJECTED_PREFLIGHT. A successful job can still publish an artifact.failed event if durable artifact publication fails.

Quote before charging

print_recipe is the only action without a fixed cost. Submit the complete recipe and source version to POST /api/v1/print-recipes/quote. The response supplies a short-lived quoteId and credit amount. Submit the same recipe to the version action endpoint with that quote; the server rejects stale, changed, or already-claimed quotes.

const quote = await api('POST', '/api/v1/print-recipes/quote', {
  sourceVersionId,
  recipe: {
    schemaVersion: 2,
    process: 'fdm',
    preparationPresetId: 'fdm-standard',
    sizing: { kind:'dimension', axis:'z', value:120, unit:'mm', origin:'bottom-center', ground:true },
    fixes: { automaticRepair:true, fillReviewedOpenings:true, rebuildAsSolid:false },
    structural: { kind:'none' },
    review: { acceptedInspectionRevision, acceptedAt: new Date().toISOString() }
  }
});
await api('POST', `/api/v1/versions/${sourceVersionId}/actions`, {
  action: 'print_recipe', quoteId: quote.quoteId,
  idempotencyKey: 'recipe-claim-unique', printRecipe: quote.recipe
});

A recipe must include its inspection revision acceptance, sizing, fixes, structural stage, and review fields. FDM hollowing additionally requires the explicit acknowledgement described by the schema.

Signed webhooks

Webhook endpoints require the webhooks:manage scope. Use GET /api/v1/webhook-endpoints to list endpoints and DELETE /api/v1/webhook-endpoints/:endpointId to remove one. Endpoints must be absolute HTTPS URLs with a publicly resolvable, non-private address. Create the endpoint once; the signing secret is returned only on creation.

curl -X POST "$MESSYPOLY_API_URL/api/v1/webhook-endpoints" \
  -H "Authorization: Bearer $MESSYPOLY_API_KEY" \
  -H "Idempotency-Key: webhook-endpoint-1" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/messypoly/webhook","eventTypes":["job.completed","job.failed","artifact.completed","artifact.failed"]}'

Verify before parsing

Read the raw request body without re-serializing it. Compute HMAC-SHA256 over {timestamp}.{rawBody} with the one-time whsec_… secret. Compare the hex digest in MessyPoly-Webhook-Signature: v1=… with a constant-time comparison and reject timestamps older than five minutes.

MessyPoly-Webhook-Id: evt_job_job_123_job_completed
MessyPoly-Webhook-Timestamp: 1786200000
MessyPoly-Webhook-Signature: v1=hex_hmac_sha256(timestamp + "." + raw_body)

Deliveries are POSTed as JSON, retried after non-2xx responses or network failures, and deduplicated by stable event ID per endpoint. Acknowledge quickly and process asynchronously. Payloads never contain presigned download URLs; fetch artifacts from the authenticated artifacts endpoint.

Errors and safe retries