From nothing to a mesh in your project

Five minutes, one key, one job. This guide uses a prop, because props skip both human gates and run straight through — add rig: true or variants: 2 once the happy path works. Every request below goes to the live API at bevel.foo.

1. 1

   Get a key

   There's no public sign-up — ask your bevel operator for a key. Keys are owner-issued and scoped (see API keys once you're signed in).

2. 2

   Verify it

   Confirm your key works and see your real quota before building anything on it.

   shell

   curl https://bevel.foo/v1/usage \
     -H "Authorization: Bearer $BEVEL_KEY"

3. 3

   Create a job

   Idempotency-Key is optional but real: a retried request with the same key and body never double-creates a job.

   shell

   curl https://bevel.foo/v1/jobs \
     -H "Authorization: Bearer $BEVEL_KEY" \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: my-first-job" \
     -d '{
       "prompt": "a weathered oak treasure chest",
       "kind": "prop",
       "export_formats": ["glb"]
     }'

   A 202 comes back with a Location header pointing at your new job. Save the job's id as $JOB.

4. 4

   Wait for it to finish

   ?wait=N (up to 50 seconds) long-polls instead of you writing your own retry loop.

   shell

   until [ "$(curl -s "https://bevel.foo/v1/jobs/$JOB?wait=50" \
       -H "Authorization: Bearer $BEVEL_KEY" | jq -r .terminal)" = "true" ]; do
     echo "still working..."
   done

   Most jobs finish as succeeded. Two states pause for a real decision instead: awaiting_selection and awaiting_rig_review — see the full reference for POST .../select-variant and POST .../approve-rig.

   Prefer push? Register a webhook endpoint and listen for job.succeeded, job.failed and the two gate events. Deliveries are signed.

5. 5

   Download the mesh

   List the job's artifacts and pull the final_glb. Bytes stay retrievable for 90 days; after that the row still lists but the content endpoint answers 410.

   shell

   ART=$(curl -s "https://bevel.foo/v1/jobs/$JOB/artifacts" \
     -H "Authorization: Bearer $BEVEL_KEY" \
     | jq -r '.data[] | select(.kind=="final_glb") | .id')
   
   curl -L -o treasure-chest.glb \
     "https://bevel.foo/v1/artifacts/$ART/content" \
     -H "Authorization: Bearer $BEVEL_KEY"

   The content endpoint 302s to a signed, time-limited URL — -L follows it.