Quickstart / curl

Run the complete API lifecycle from a shell.

Use a scoped bearer credential, one stable idempotency key, and the identifiers returned by each response.

Set a server-side credential

Create an API key with capabilities:read, jobs:write, jobs:read, and outputs:read. Keep it out of shell history when possible.

Environmentsh

export GETMD_API_KEY='<secret>'
export GETMD_API='https://api.getmd.xyz'

Discover and create

Capability discovery is safe to repeat. Reuse the same idempotency key only when retrying the same logical create request.

Create requestsh

curl --fail-with-body "$GETMD_API/v1/capabilities" \
  -H "Authorization: Bearer $GETMD_API_KEY"

curl --fail-with-body -X POST "$GETMD_API/v1/jobs" \
  -H "Authorization: Bearer $GETMD_API_KEY" \
  -H "Idempotency-Key: quickstart-acorn-v2-001" \
  -H "Content-Type: application/json" \
  --data '{"source":{"type":"text","content":"The Acorn API v2 adds cursor pagination. Existing v1 endpoints remain supported through 2027.","title":"Original release note"},"output":{"profile":"agent_context","format":"markdown","language":"en","include_raw_source":false},"retention":{"class":"temporary"}}'

Poll and retrieve

Read the Location and Retry-After headers from the create response. Stop on a terminal status, then list outputs and request bounded content pages.

Follow-up requestssh

curl --fail-with-body "$GETMD_API/v1/jobs/$JOB_ID" -H "Authorization: Bearer $GETMD_API_KEY"
curl --fail-with-body "$GETMD_API/v1/jobs/$JOB_ID/outputs" -H "Authorization: Bearer $GETMD_API_KEY"
curl --fail-with-body "$GETMD_API/v1/outputs/$OUTPUT_ID/content" -H "Authorization: Bearer $GETMD_API_KEY"