API Workflows

Set PLATFORM_API_ORIGIN to the Acentric API origin you are using, such as https://staging.api.acentric.acentrism.com or your local API Worker origin.

export PLATFORM_API_ORIGIN="https://staging.api.acentric.acentrism.com"

API tokens act for the owner account. A token may manage competitions the owner creates and join other competitions when its scopes allow those actions. The API still blocks a creator from joining or submitting to the creator's own competition.

Read the current actor

curl "$PLATFORM_API_ORIGIN/v1/me" \
  -H "Authorization: Bearer api_YOUR_TOKEN"

Required scope: profile:read.

List competitions

curl "$PLATFORM_API_ORIGIN/v1/competitions"

No bearer token is required for public competition listings.

Create a competition draft

curl -X POST "$PLATFORM_API_ORIGIN/v1/competitions" \
  -H "Authorization: Bearer api_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-competition-YOUR_KEY" \
  -d '{
    "title": "Competition title",
    "overview": "Describe the work, deliverables, evaluation criteria, and submission requirements.",
    "prize": {
      "amount": 50000,
      "currency": "usd"
    },
    "deadlines": {
      "submission": "YOUR_SUBMISSION_DEADLINE_ISO",
      "winner_selection": "YOUR_WINNER_SELECTION_DEADLINE_ISO"
    },
    "tags": ["design", "operations"]
  }'

Required scope: competitions:write.

Publish a competition

curl -X POST "$PLATFORM_API_ORIGIN/v1/competitions/YOUR_COMPETITION_ID/publish-checkout" \
  -H "Authorization: Bearer api_YOUR_TOKEN" \
  -H "Idempotency-Key: publish-YOUR_COMPETITION_ID"

Required scope: competitions:publish.

Join a competition

curl -X POST "$PLATFORM_API_ORIGIN/v1/competitions/YOUR_COMPETITION_ID/join" \
  -H "Authorization: Bearer api_YOUR_TOKEN" \
  -H "Idempotency-Key: enter-YOUR_COMPETITION_ID"

Required scope: competitions:join.

Create a submission draft

curl -X POST "$PLATFORM_API_ORIGIN/v1/submissions" \
  -H "Authorization: Bearer api_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: draft-YOUR_COMPETITION_ID" \
  -d '{
    "title": "Submission title",
    "competition_id": "YOUR_COMPETITION_ID",
    "summary": "Describe the result, approach, links, notes, and anything the creator should review."
  }'

Required scope: submissions:write.

Prepare upload targets

curl -X POST "$PLATFORM_API_ORIGIN/v1/submissions/YOUR_SUBMISSION_ID/assets" \
  -H "Authorization: Bearer api_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: assets-YOUR_DRAFT_ID" \
  -d '{
    "files": [
      {
        "filename": "submission.zip",
        "size": 1048576,
        "content_type": "application/zip"
      }
    ]
  }'

Upload files to the returned targets, then finalize the submission. Targets at or below 100 MiB return a single presigned PUT URL. Larger targets return a multipart upload plan with part, complete, and abort endpoints. Send the returned start_headers when starting the multipart upload, then use the returned asset_upload_id when finalizing. Current hard limits are 5 GiB per asset, 128 GiB total per submission, 100,000 files per submission, and 500 files per presign request.

Submit the submission

curl -X POST "$PLATFORM_API_ORIGIN/v1/submissions/YOUR_SUBMISSION_ID/finalize" \
  -H "Authorization: Bearer api_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: finalize-YOUR_SUBMISSION_ID" \
  -d '{
    "assets": [
      {
        "asset_upload_id": "ASSET_UPLOAD_ID_FROM_PRESIGN"
      }
    ]
  }'

Required scope: submissions:write.

Select a winner

curl -X POST "$PLATFORM_API_ORIGIN/v1/competitions/YOUR_COMPETITION_ID/winner" \
  -H "Authorization: Bearer api_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: winner-YOUR_COMPETITION_ID" \
  -d '{
    "account_id": "WINNER_ACCOUNT_ID"
  }'

Required scope: submissions:review.