Get started

Create a token

Log in to Codykata and open Settings → “API tokens” from the account menu. Choose a name, scopes and lifetime (7, 30 or 90 days, 1 year, a date, or no expiry). The token is shown only once, so copy it right away and keep it safe. You can revoke it on the same screen at any time.

Open API token settings

Every token can read your profile summary, public problems, sources and licenses. Pick only the scopes you need.

Authentication

Send the token in the Authorization header of every request. The base URL is https://api.codykata.com/v1, and bodies are JSON.

curl -H "Authorization: Bearer $CODYKATA_TOKEN" \
  https://api.codykata.com/v1/me

Treat the token like a password: never commit it, and keep it in an environment variable or secret store. Revoke and replace it as soon as you suspect a leak. Tokens never carry administrator rights, and logging out other browsers does not revoke them.

Endpoints

Paths are relative to https://api.codykata.com/v1. See request and response shapes, and try calls, in the API reference. Open the API reference

Hand the OpenAPI document to agents and client generators as is. openapi.json

Examples

Check your tier

curl -s -H "Authorization: Bearer $CODYKATA_TOKEN" https://api.codykata.com/v1/me

{
  "user_id": "…",
  "name": "…",
  "tier": "Gold",
  "current_sp": 412,
  "next_tier": { "tier": "Platinum", "required_sp": 700 },
  "solved_count": 58,
  "current_streak": 6,
  "longest_streak": 21,
  "rank": { "points": 37 },
  "token": { "id": "…", "name": "…", "scopes": ["read"], "expires_at": null }
}

rank.points is your points ranking and is null while your profile is private. Use token to check this token’s scopes and expiry.

Submit and wait for the result

Read the problem first to get its problem_version_id and submit against that version. Judging is asynchronous, so poll every few seconds until status is FINISHED or SYSTEM_FAILED.

curl -s -X POST https://api.codykata.com/v1/submissions \
  -H "Authorization: Bearer $CODYKATA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"problem_id":"…","problem_version_id":"…","language":"python","code":"print(1)"}'

curl -s -H "Authorization: Bearer $CODYKATA_TOKEN" https://api.codykata.com/v1/submissions/<submission_id>

language is one of cpp, c, python, javascript and typescript. Submissions have no idempotency key, so a resend after a lost response may create a duplicate; check /submissions before resending.

Submit a problem

POST /problems creates a review request; the problem goes public once an administrator approves it. Generate a new request_id (UUID) per problem; after a lost response, resend the same request_id with the same content to get the first result back. The body uses the same ProblemPackage v2 as the web editor, up to 32 MiB. To edit, send PUT /studio/problems/:id with the last saved version as expected_version_id.

Errors

Errors look like {"error": "...", "message": "..."}. Branch on the HTTP status first and use error only to tell business reasons apart; message is for people and may change.

Limits

• Read requests: 120 per minute per token.
• Write requests: 30 per minute per account, shared with the web app. More tokens do not raise it.
• Up to 10 unfinished submissions per account.
• Problem submissions and edits through tokens: 10 per account per UTC day.
• Up to 20 active tokens per account.

On 429, wait before retrying. Do not resend submissions automatically.

Compatibility

Within v1, responses only gain optional fields. Removing, renaming or retyping a field ships under a new version path. Write clients that ignore unknown fields.