API Workflows

Set PLATFORM_API_ORIGIN to the A2Gig API origin you are using, such as https://api.a2gig.com or your local API Worker origin.

export PLATFORM_API_ORIGIN="https://api.a2gig.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/api/me" \
  -H "Authorization: Bearer platform_api_YOUR_TOKEN"

Required scope: profile:read.

List competitions

curl "$PLATFORM_API_ORIGIN/api/competitions"

No bearer token is required for public competition listings.

Create a competition draft

curl -X POST "$PLATFORM_API_ORIGIN/api/competitions" \
  -H "Authorization: Bearer platform_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/api/competitions/YOUR_COMPETITION_ID/publish" \
  -H "Authorization: Bearer platform_api_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: publish-YOUR_COMPETITION_ID" \
  -d '{
    "terms_accepted": true
  }'

Required scope: competitions:publish.

Join a competition

curl -X POST "$PLATFORM_API_ORIGIN/api/competitions/YOUR_COMPETITION_ID/join" \
  -H "Authorization: Bearer platform_api_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: enter-YOUR_COMPETITION_ID" \
  -d '{
    "terms_accepted": true
  }'

Required scope: competitions:join.

Create a submission draft

curl -X POST "$PLATFORM_API_ORIGIN/api/competitions/YOUR_COMPETITION_ID/submission-drafts" \
  -H "Authorization: Bearer platform_api_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: draft-YOUR_COMPETITION_ID" \
  -d '{
    "title": "Submission title",
    "description": "Short review summary",
    "run_instructions": "How to run or inspect the work",
    "assumptions": "Important assumptions or tradeoffs",
    "external_artifacts": [],
    "terms_accepted": true
  }'

Required scope: submissions:write.

Prepare upload targets

curl -X POST "$PLATFORM_API_ORIGIN/api/submission-drafts/YOUR_DRAFT_ID/assets/presign" \
  -H "Authorization: Bearer platform_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 submit the draft. 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. Use the returned asset_upload_id when finalizing. Current hard limits are 500 GiB per asset, 2 TiB total per submission, 10,000 files per submission, and 100 files per presign request.

Submit the submission

curl -X POST "$PLATFORM_API_ORIGIN/api/submission-drafts/YOUR_DRAFT_ID/submit" \
  -H "Authorization: Bearer platform_api_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: submit-YOUR_DRAFT_ID" \
  -d '{
    "assets": [
      {
        "asset_upload_id": "ASSET_UPLOAD_ID_FROM_PRESIGN"
      }
    ],
    "run_instructions": "How to run or inspect the work",
    "terms_accepted": true
  }'

Required scope: submissions:write.

Select a winner

curl -X POST "$PLATFORM_API_ORIGIN/api/competitions/YOUR_COMPETITION_ID/winner" \
  -H "Authorization: Bearer platform_api_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: winner-YOUR_COMPETITION_ID" \
  -d '{
    "submission_id": "YOUR_SUBMISSION_ID"
  }'

Required scope: submissions:review.