Trigger a new CI run

POST /runs

Requires runs:write scope and contributor role or above. The regression_test_ids set is validated against active tests only. If omitted, all active regression tests are used.

application/json

Body Required

repository string Required

Maximum length is 100. Format should match the following pattern: ^[a-zA-Z0-9_.-]+/[a-zA-Z0-9_.-]+$.
branch string

Maximum length is 100. Format should match the following pattern: ^[A-Za-z0-9._\/-]+$.
commit_sha string Required

Format should match the following pattern: ^[a-fA-F0-9]{40}$.
pull_request integer | null

Minimum value is 1.
platform string Required

Values are linux or windows.
regression_test_ids array[integer]

Optional subset of active regression test IDs. If omitted, all active tests are used. Inactive test IDs are rejected with 422.

Not more than 500 elements. Minimum value of each is 1.
environment_id string

Maximum length is 50.

Responses

202 application/json

Run queued. Poll /runs/{run_id}/progress for status.
Hide response attributes Show response attributes object
- run_id integer Required
  
  Minimum value is 1.
- status string Required
  
  Normalized status. Derived from TestProgress rows and TestResult outcomes. status=canceled covers both explicit cancellation and infrastructure error (the underlying model conflates them).
  
  Values are queued, running, pass, fail, canceled, error, or incomplete.
- repository string Required
  
  Maximum length is 100.
- branch string | null
  
  Maximum length is 100.
- commit_sha string Required
  
  Format should match the following pattern: ^[a-fA-F0-9]{40}$.
- commit_short string
  
  Maximum length is 10.
- pull_request integer | null
  
  Minimum value is 1.
- platform string Required
  
  Values are linux or windows.
- run_errors string
  
  Values are true, false, or unknown.
- triggered_by string | null
  
  Maximum length is 100.
- created_at string(date-time) Required
- queued_at string(date-time) | null
- started_at string(date-time) | null
- completed_at string(date-time) | null
- duration_ms integer | null
  
  Minimum value is 0.
- links object
  
  Hide links attribute Show links attribute object
  
  * string(uri) Additional properties
400 application/json

Request body or query parameters failed schema validation
Hide response attributes Show response attributes object
- code string Required
  
  Machine-readable error code (snake_case)
  
  Maximum length is 100.
- message string Required
  
  Human-readable error summary
  
  Maximum length is 500.
- details object Required
  
  Structured context for the error. Always an object, never null. Empty object {} when no additional detail is available.
  
  Additional properties are allowed.
401 application/json

Missing, expired, or invalid bearer token
Hide response attributes Show response attributes object
- code string Required
  
  Machine-readable error code (snake_case)
  
  Maximum length is 100.
- message string Required
  
  Human-readable error summary
  
  Maximum length is 500.
- details object Required
  
  Structured context for the error. Always an object, never null. Empty object {} when no additional detail is available.
  
  Additional properties are allowed.
403 application/json

Token is valid but lacks the required scope or role
Hide response attributes Show response attributes object
- code string Required
  
  Machine-readable error code (snake_case)
  
  Maximum length is 100.
- message string Required
  
  Human-readable error summary
  
  Maximum length is 500.
- details object Required
  
  Structured context for the error. Always an object, never null. Empty object {} when no additional detail is available.
  
  Additional properties are allowed.
422 application/json

Request is valid JSON but semantically invalid
Hide response attributes Show response attributes object
- code string Required
  
  Machine-readable error code (snake_case)
  
  Maximum length is 100.
- message string Required
  
  Human-readable error summary
  
  Maximum length is 500.
- details object Required
  
  Structured context for the error. Always an object, never null. Empty object {} when no additional detail is available.
  
  Additional properties are allowed.
429 application/json

Too many requests. Retry after the indicated number of seconds.
Hide headers attributes Show headers attributes
- Retry-After integer
  
  Seconds to wait before retrying
- X-RateLimit-Limit
  
  Maximum requests allowed in the current window
- X-RateLimit-Remaining
  
  Requests remaining in the current window
- X-RateLimit-Reset
  
  Unix timestamp when the rate limit window resets
Hide response attributes Show response attributes object
- code string Required
  
  Machine-readable error code (snake_case)
  
  Maximum length is 100.
- message string Required
  
  Human-readable error summary
  
  Maximum length is 500.
- details object Required
  
  Structured context for the error. Always an object, never null. Empty object {} when no additional detail is available.
  
  Additional properties are allowed.
default application/json

Unexpected server error
Hide response attributes Show response attributes object
- code string Required
  
  Machine-readable error code (snake_case)
  
  Maximum length is 100.
- message string Required
  
  Human-readable error summary
  
  Maximum length is 500.
- details object Required
  
  Structured context for the error. Always an object, never null. Empty object {} when no additional detail is available.
  
  Additional properties are allowed.

POST /runs

curl \
 --request POST 'https://sampleplatform.ccextractor.org/api/v1/runs' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json" \
 --data '{"repository":"CCExtractor/ccextractor","branch":"master","commit_sha":"0632bff4e382d5f86eff9073b9ddd37f03f9778c","pull_request":2264,"platform":"windows","regression_test_ids":[42],"environment_id":"windows-latest"}'

Request examples

{
  "repository": "CCExtractor/ccextractor",
  "branch": "master",
  "commit_sha": "0632bff4e382d5f86eff9073b9ddd37f03f9778c",
  "pull_request": 2264,
  "platform": "windows",
  "regression_test_ids": [
    42
  ],
  "environment_id": "windows-latest"
}

Response examples (202)

{
  "run_id": 42,
  "status": "queued",
  "repository": "string",
  "branch": "string",
  "commit_sha": "string",
  "commit_short": "string",
  "pull_request": 42,
  "platform": "linux",
  "run_errors": true,
  "triggered_by": "string",
  "created_at": "2026-05-04T09:42:00Z",
  "queued_at": "2026-05-04T09:42:00Z",
  "started_at": "2026-05-04T09:42:00Z",
  "completed_at": "2026-05-04T09:42:00Z",
  "duration_ms": 42,
  "links": {
    "additionalProperty1": "https://example.com",
    "additionalProperty2": "https://example.com"
  }
}

Response examples (400)

{
  "code": "validation_error",
  "message": "Request failed schema validation.",
  "details": {
    "fields": {
      "commit_sha": "Must match pattern ^[a-fA-F0-9]{40}$",
      "platform": "Must be one of [linux, windows]"
    }
  }
}

Response examples (401)

{
  "code": "unauthorized",
  "message": "Bearer token is missing, expired, or invalid.",
  "details": {}
}

Response examples (403)

{
  "code": "forbidden",
  "message": "Token does not have the required scope for this operation.",
  "details": {
    "required_scope": "runs:write",
    "token_scopes": [
      "runs:read",
      "results:read"
    ]
  }
}

Response examples (422)

{
  "code": "unprocessable",
  "message": "regression_test_ids contains inactive test IDs.",
  "details": {
    "inactive_ids": [
      42,
      99
    ]
  }
}

Response examples (429)

{
  "code": "rate_limited",
  "message": "Rate limit exceeded. Retry after 30 seconds.",
  "details": {
    "retry_after": 30,
    "limit": 120,
    "window": "60s"
  }
}

Response examples (default)

{
  "code": "not_found",
  "message": "Run 9317 not found.",
  "details": {}
}