Forithmus Challenges API
The challenges API from Forithmus — 7 operation(s) for challenges.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/forithmus:forithmus-challenges-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Forithmus Challenge Platform Challenges API
version: 1.0.0
tags:
- name: Challenges
paths:
/challenges/meta/categories:
get:
tags:
- Challenges
summary: List Categories
description: 'List all distinct challenge categories currently in use, sorted alphabetically.
Used by frontend for dynamic category dropdowns and browse filters.'
operationId: list_categories_challenges_meta_categories_get
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
/challenges:
get:
tags:
- Challenges
summary: List Challenges
description: 'List public challenges with pagination.
If mine=true (requires auth), returns all challenges the user is an active member of.
Returns: { items: [...], total: int, limit: int, offset: int }'
operationId: list_challenges_challenges_get
parameters:
- name: status
in: query
required: false
schema:
type: string
default: open
title: Status
- name: category
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Category
- name: mine
in: query
required: false
schema:
type: boolean
default: false
title: Mine
- name: limit
in: query
required: false
schema:
type: integer
maximum: 100
minimum: 1
default: 20
title: Limit
- name: offset
in: query
required: false
schema:
type: integer
minimum: 0
default: 0
title: Offset
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
post:
tags:
- Challenges
summary: Create Challenge
description: 'Create a new challenge in ''draft'' status. Requires email verification.
The creator is automatically added as a ChallengeMember with role=''admin''.
After creation, the admin must upload test data and evaluation container,
then transition status to ''open'' via PUT.'
operationId: create_challenge_challenges_post
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ChallengeCreate'
responses:
'201':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ChallengeOut'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/challenges/{slug}/registry-usage:
get:
tags:
- Challenges
summary: Get Registry Usage Endpoint
description: Get Docker registry storage usage for this challenge. Admin only.
operationId: get_registry_usage_endpoint_challenges__slug__registry_usage_get
parameters:
- name: slug
in: path
required: true
schema:
type: string
title: Slug
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/challenges/{slug}/registry-purge:
post:
tags:
- Challenges
summary: Purge Registry
description: Delete all kept Docker images for this challenge. Admin only.
operationId: purge_registry_challenges__slug__registry_purge_post
parameters:
- name: slug
in: path
required: true
schema:
type: string
title: Slug
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/challenges/{slug}/stats:
get:
tags:
- Challenges
summary: Get Challenge Stats
description: 'Stats for a challenge: participants by country/institution, submission stats.
Private challenges require membership. Public challenges are open to all.
Cached in Redis for 5 minutes to avoid expensive aggregation queries on every load.'
operationId: get_challenge_stats_challenges__slug__stats_get
parameters:
- name: slug
in: path
required: true
schema:
type: string
title: Slug
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/challenges/by-id/{challenge_id}:
get:
tags:
- Challenges
summary: Get Challenge By Id
description: Look up a challenge slug by its UUID. Used by notifications.
operationId: get_challenge_by_id_challenges_by_id__challenge_id__get
parameters:
- name: challenge_id
in: path
required: true
schema:
type: string
title: Challenge Id
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/challenges/{slug}:
get:
tags:
- Challenges
summary: Get Challenge
description: 'Get challenge details. Private challenges require active membership.
Platform superadmin/staff can always view.'
operationId: get_challenge_challenges__slug__get
parameters:
- name: slug
in: path
required: true
schema:
type: string
title: Slug
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ChallengeOut'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
put:
tags:
- Challenges
summary: Update Challenge
description: 'Update challenge settings. Only challenge admins can update.
Platform superadmin/staff also have access (handled by require_challenge_role).
Status changes are validated against ALLOWED_STATUS_TRANSITIONS
(e.g. draft->open, open->closed). All other fields are freely editable.'
operationId: update_challenge_challenges__slug__put
parameters:
- name: slug
in: path
required: true
schema:
type: string
title: Slug
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ChallengeUpdate'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ChallengeOut'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
delete:
tags:
- Challenges
summary: Delete Challenge
description: 'Delete a challenge and all related data (members, phases, pages, forum, submissions).
Only challenge admins or platform superadmin/staff can delete.
Cascade delete is handled by the database (ondelete=CASCADE on foreign keys).'
operationId: delete_challenge_challenges__slug__delete
parameters:
- name: slug
in: path
required: true
schema:
type: string
title: Slug
responses:
'204':
description: Successful Response
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
components:
schemas:
ChallengeUpdate:
properties:
title:
anyOf:
- type: string
maxLength: 200
- type: 'null'
title: Title
acronym:
anyOf:
- type: string
maxLength: 20
- type: 'null'
title: Acronym
description:
anyOf:
- type: string
- type: 'null'
title: Description
category:
anyOf:
- type: string
- type: 'null'
title: Category
visibility:
anyOf:
- type: string
- type: 'null'
title: Visibility
status:
anyOf:
- type: string
- type: 'null'
title: Status
tier:
anyOf:
- type: string
- type: 'null'
title: Tier
timeout_minutes:
anyOf:
- type: integer
maximum: 360.0
minimum: 5.0
- type: 'null'
title: Timeout Minutes
max_submissions_per_user:
anyOf:
- type: integer
maximum: 100.0
minimum: 1.0
- type: 'null'
title: Max Submissions Per User
score_json_path:
anyOf:
- type: string
- type: 'null'
title: Score Json Path
sort_direction:
anyOf:
- type: string
- type: 'null'
title: Sort Direction
deadline:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Deadline
forum_enabled:
anyOf:
- type: boolean
- type: 'null'
title: Forum Enabled
timeline_enabled:
anyOf:
- type: boolean
- type: 'null'
title: Timeline Enabled
groups_enabled:
anyOf:
- type: boolean
- type: 'null'
title: Groups Enabled
require_approval:
anyOf:
- type: boolean
- type: 'null'
title: Require Approval
current_edition:
anyOf:
- type: string
- type: 'null'
title: Current Edition
editions:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Editions
resource_overrides:
anyOf:
- items:
type: object
type: array
- type: 'null'
title: Resource Overrides
eval_cost_limit:
anyOf:
- type: number
maximum: 1000.0
minimum: 1.0
- type: 'null'
title: Eval Cost Limit
participant_pays_compute:
anyOf:
- type: boolean
- type: 'null'
title: Participant Pays Compute
spot_enabled:
anyOf:
- type: boolean
- type: 'null'
title: Spot Enabled
keep_docker_images:
anyOf:
- type: boolean
- type: 'null'
title: Keep Docker Images
keep_submission_outputs:
anyOf:
- type: boolean
- type: 'null'
title: Keep Submission Outputs
hide_submission_logs:
anyOf:
- type: boolean
- type: 'null'
title: Hide Submission Logs
storage_price_per_tb:
anyOf:
- type: number
- type: 'null'
title: Storage Price Per Tb
storage_free_tier_gb:
anyOf:
- type: number
- type: 'null'
title: Storage Free Tier Gb
registry_limit_gb:
anyOf:
- type: number
- type: 'null'
title: Registry Limit Gb
registry_price_per_gb:
anyOf:
- type: number
- type: 'null'
title: Registry Price Per Gb
output_limit_gb:
anyOf:
- type: number
- type: 'null'
title: Output Limit Gb
eval_excess_enabled:
anyOf:
- type: boolean
- type: 'null'
title: Eval Excess Enabled
cover_image_url:
anyOf:
- type: string
- type: 'null'
title: Cover Image Url
card_image_url:
anyOf:
- type: string
- type: 'null'
title: Card Image Url
cover_image_original_url:
anyOf:
- type: string
- type: 'null'
title: Cover Image Original Url
card_image_original_url:
anyOf:
- type: string
- type: 'null'
title: Card Image Original Url
type: object
title: ChallengeUpdate
description: 'Request body for PUT /challenges/{slug}: all fields optional (partial update).
Note: visibility is intentionally excluded: it is set at creation and cannot be changed.'
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
type: object
required:
- loc
- msg
- type
title: ValidationError
ChallengeCreate:
properties:
title:
type: string
maxLength: 200
minLength: 1
title: Title
acronym:
type: string
maxLength: 20
minLength: 1
title: Acronym
description:
type: string
title: Description
default: ''
category:
type: string
title: Category
default: Segmentation
visibility:
type: string
title: Visibility
default: public
tier:
type: string
title: Tier
default: gpu-t4
timeout_minutes:
type: integer
maximum: 360.0
minimum: 5.0
title: Timeout Minutes
default: 60
max_submissions_per_user:
type: integer
maximum: 100.0
minimum: 1.0
title: Max Submissions Per User
default: 10
score_json_path:
type: string
title: Score Json Path
default: $.metrics.dice
sort_direction:
type: string
title: Sort Direction
default: desc
deadline:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Deadline
type: object
required:
- title
- acronym
title: ChallengeCreate
description: 'Request body for POST /challenges: creates a new challenge in ''draft'' status.'
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
ChallengeOut:
properties:
id:
type: string
format: uuid
title: Id
slug:
type: string
title: Slug
collection_id:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Collection Id
title:
type: string
title: Title
acronym:
type: string
title: Acronym
default: ''
collection_acronym:
anyOf:
- type: string
- type: 'null'
title: Collection Acronym
description:
type: string
title: Description
category:
type: string
title: Category
visibility:
type: string
title: Visibility
status:
type: string
title: Status
tier:
type: string
title: Tier
timeout_minutes:
type: integer
title: Timeout Minutes
max_submissions_per_user:
type: integer
title: Max Submissions Per User
score_json_path:
type: string
title: Score Json Path
sort_direction:
type: string
title: Sort Direction
submission_count:
type: integer
title: Submission Count
participant_count:
type: integer
title: Participant Count
default: 0
forum_enabled:
type: boolean
title: Forum Enabled
timeline_enabled:
type: boolean
title: Timeline Enabled
default: true
groups_enabled:
type: boolean
title: Groups Enabled
default: false
require_approval:
type: boolean
title: Require Approval
default: false
current_edition:
anyOf:
- type: string
- type: 'null'
title: Current Edition
editions:
items:
type: string
type: array
title: Editions
default: []
has_sponsor_pool:
type: boolean
title: Has Sponsor Pool
default: false
resource_overrides:
items:
type: object
type: array
title: Resource Overrides
default: []
eval_cost_limit:
type: number
title: Eval Cost Limit
default: 20.0
participant_pays_compute:
type: boolean
title: Participant Pays Compute
default: false
spot_enabled:
type: boolean
title: Spot Enabled
default: false
keep_docker_images:
type: boolean
title: Keep Docker Images
default: false
keep_submission_outputs:
type: boolean
title: Keep Submission Outputs
default: false
registry_purge_after:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Registry Purge After
data_retention_until:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Data Retention Until
hide_submission_logs:
type: boolean
title: Hide Submission Logs
default: false
storage_price_per_tb:
anyOf:
- type: number
- type: 'null'
title: Storage Price Per Tb
storage_free_tier_gb:
anyOf:
- type: number
- type: 'null'
title: Storage Free Tier Gb
registry_limit_gb:
anyOf:
- type: number
- type: 'null'
title: Registry Limit Gb
output_limit_gb:
anyOf:
- type: number
- type: 'null'
title: Output Limit Gb
eval_excess_enabled:
type: boolean
title: Eval Excess Enabled
default: false
subscription_status:
anyOf:
- type: string
- type: 'null'
title: Subscription Status
host_user_id:
type: string
format: uuid
title: Host User Id
deadline:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Deadline
cover_image_url:
anyOf:
- type: string
- type: 'null'
title: Cover Image Url
card_image_url:
anyOf:
- type: string
- type: 'null'
title: Card Image Url
cover_image_original_url:
anyOf:
- type: string
- type: 'null'
title: Cover Image Original Url
card_image_original_url:
anyOf:
- type: string
- type: 'null'
title: Card Image Original Url
created_at:
type: string
format: date-time
title: Created At
updated_at:
type: string
format: date-time
title: Updated At
type: object
required:
- id
- slug
- title
- description
- category
- visibility
- status
- tier
- timeout_minutes
- max_submissions_per_user
- score_json_path
- sort_direction
- submission_count
- forum_enabled
- host_user_id
- deadline
- created_at
- updated_at
title: ChallengeOut
description: Full challenge representation returned by detail endpoints.
x-provenance:
method: harvested
publisher: Forithmus
source: https://research.forithmus.com/api/openapi.json
note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
stamped by stamp-openapi-provenance.py (roadmap#793)