Sources API

Overview

The Sources API manages hosted cloud sources and the per-source eval-suggestion review loop. Base path:

/api/v1/cloud-sources

All endpoints require an API key:

Authorization: Bearer st_live_...

Endpoints

Method	Path	Purpose
`GET`	`/api/v1/cloud-sources`	List cloud sources
`POST`	`/api/v1/cloud-sources`	Create an upload-backed or GitHub-backed source
`GET`	`/api/v1/cloud-sources/{id}`	Get enriched source detail
`POST`	`/api/v1/cloud-sources/upload`	Create a source and upload a skill folder
`POST`	`/api/v1/cloud-sources/{id}/github-sync`	Sync a GitHub-backed source into a new snapshot
`POST`	`/api/v1/cloud-sources/{id}/eval-suggestions/review`	Accept or dismiss a suggestion
`DELETE`	`/api/v1/cloud-sources/{id}/eval-suggestions/{suggestionId}/review`	Restore a reviewed suggestion to pending
`POST`	`/api/v1/cloud-sources/{id}/eval-suggestions/{suggestionId}/apply-to-suite`	Append a suggestion directly into a saved suite

List sources

GET /api/v1/cloud-sources
Authorization: Bearer {API_KEY}

Query parameters

Parameter	Type	Description
`type`	`upload` \| `github`	Optional source-type filter
`skill_id`	UUID	Optional linked-skill filter

Response

[
  {
    "id": "src_12345678-1234-1234-1234-123456789abc",
    "label": "sc-search",
    "sourceType": "upload",
    "skillId": "skill_12345678-1234-1234-1234-123456789abc",
    "createdAt": "2026-04-18T09:00:00.000Z"
  }
]

Create a source

Creates a source shell for either an upload-backed or GitHub-backed skill.

POST /api/v1/cloud-sources
Content-Type: application/json
Authorization: Bearer {API_KEY}

Upload-backed source

{
  "type": "upload",
  "label": "sc-search"
}

GitHub-backed source

{
  "type": "github",
  "label": "state-change-search",
  "installation_id": 12345678,
  "repo_full_name": "state-change/search-skill",
  "default_branch": "main",
  "skill_path": "skills/sc-search"
}

Response

{
  "id": "src_12345678-1234-1234-1234-123456789abc",
  "label": "state-change-search",
  "sourceType": "github",
  "skillId": null,
  "repoFullName": "state-change/search-skill"
}

Get source detail

Returns the enriched source detail used by the cloud skill page, including current snapshot, validation reports, eval suggestions, and reviewed suggestion history.

GET /api/v1/cloud-sources/{id}
Authorization: Bearer {API_KEY}

Upload a source snapshot

Creates a source and uploads a skill folder in one request.

POST /api/v1/cloud-sources/upload
Content-Type: multipart/form-data
Authorization: Bearer {API_KEY}

Form fields

Field	Type	Required	Description
`label`	string	Yes	Display label for the source
`skill_id`	UUID	No	Optional canonical skill link
`file` or relative-path field keys	file	Yes	Zip archive or uploaded files

When uploading individual files, use the relative path as the multipart field key to preserve directory structure.

Sync from GitHub

Triggers a fresh sync for an existing GitHub-backed source and creates a new snapshot.

POST /api/v1/cloud-sources/{id}/github-sync
Authorization: Bearer {API_KEY}

Eval suggestion reviews

Eval suggestions are AI-generated test cases surfaced from telemetry or recent runs. When you accept or dismiss a suggestion from the dashboard, a review record is created. You can clear that record to move the suggestion back into the pending queue.

Review an eval suggestion

Accepts or dismisses an AI-generated eval suggestion. Accepted suggestions can be tracked as draft accepts so they do not silently mutate the saved suite.

POST /api/v1/cloud-sources/{sourceId}/eval-suggestions/review
Content-Type: application/json
Authorization: Bearer {API_KEY}

Request fields

Field	Type	Required	Description
`suggestion_id`	UUID	Yes	The suggestion to review
`query`	string	Yes	Query text for the case
`should_trigger`	boolean	Yes	Whether the skill should trigger
`review_status`	`accepted` \| `rejected`	Yes	Review decision
`source`	`linked_telemetry` \| `hosted_run`	Yes	Evidence source
`provenance`	`failed_evaluation` \| `missed_query` \| `run_regression` \| `run_failure`	Yes	Why it was suggested
`accept_target`	`draft` \| `saved_suite`	No	For accepted cases, whether this was draft-only or a direct suite write
`applied_suite_id`	UUID	No	Saved-suite target when applicable
`rationale`	string	No	Human-readable explanation
`observed_count`	number	No	Number of observed examples
`confidence`	number	No	Confidence score
`last_observed_at`	ISO 8601 string	No	Last observation time
`invocation_type`	string	No	Invocation mode for positive trigger cases

Response

{
  "review": {
    "id": "rev_xxxxxxxxxxxxxxxx",
    "suggestionId": "sug_xxxxxxxxxxxxxxxx",
    "reviewStatus": "accepted",
    "acceptTarget": "draft",
    "appliedSuiteId": null,
    "query": "deploy my staging environment"
  }
}

Clear an eval suggestion review

Removes the review decision for a single suggestion, returning it to the pending queue so it can be re-evaluated.

DELETE /api/v1/cloud-sources/{sourceId}/eval-suggestions/{suggestionId}/review
Authorization: Bearer {API_KEY}

Path parameters

Parameter	Type	Description
`sourceId`	UUID	The cloud source ID
`suggestionId`	UUID	The suggestion ID whose review to clear

Response

Returns 204 No Content on success with no response body.

Error responses

{
  "error": {
    "message": "Review not found",
    "status": 404
  }
}

Status	Description
`204`	Review cleared — suggestion is now pending again
`404`	No review exists for this suggestion on this source
`403`	The source does not belong to your organization

Example

curl -X DELETE https://selftune.dev/api/v1/cloud-sources/src_abc123/eval-suggestions/sug_xyz789/review \
  -H "Authorization: Bearer {API_KEY}"

Apply a suggestion directly to a saved suite

Appends a suggestion into an existing llm_judge suite for the same source, then records the acceptance as saved_suite.

POST /api/v1/cloud-sources/{sourceId}/eval-suggestions/{suggestionId}/apply-to-suite
Content-Type: application/json
Authorization: Bearer {API_KEY}

Request fields

Field	Type	Required	Description
`suite_id`	UUID	Yes	Target saved eval suite
`query`	string	Yes	The query text for the suggestion
`should_trigger`	boolean	Yes	Whether the skill should trigger on this query
`source`	`linked_telemetry` \| `hosted_run`	Yes	Where the suggestion originated
`provenance`	`failed_evaluation` \| `missed_query` \| `run_regression` \| `run_failure`	Yes	Why the suggestion was raised
`rationale`	string	No	Explanation of why this case was suggested
`observed_count`	number	No	Number of times this query was observed
`confidence`	number	No	Model confidence score (0–1)
`last_observed_at`	ISO 8601 string	No	When the query was last seen
`invocation_type`	string	No	How the skill was invoked

Response

{
  "suite": {
    "id": "suite_xxxxxxxxxxxxxxxx",
    "name": "Quick Eval Suite"
  },
  "review": {
    "id": "rev_xxxxxxxxxxxxxxxx",
    "suggestionId": "sug_xxxxxxxxxxxxxxxx",
    "query": "deploy my staging environment",
    "reviewStatus": "accepted",
    "acceptTarget": "saved_suite",
    "appliedSuiteId": "suite_xxxxxxxxxxxxxxxx",
    "appliedToSuiteAt": "2026-04-18T09:00:00Z"
  }
}

Cloud platform

API reference

Overview

Endpoints

List sources

Query parameters

Response

Create a source

Upload-backed source

GitHub-backed source

Response

Get source detail

Upload a source snapshot

Form fields

Sync from GitHub

Eval suggestion reviews

Review an eval suggestion

Request fields

Response

Clear an eval suggestion review

Path parameters

Response

Error responses

Example

Apply a suggestion directly to a saved suite

Request fields

Response

Cloud platform

API reference

​Overview

​Endpoints

​List sources

​Query parameters

​Response

​Create a source

​Upload-backed source

​GitHub-backed source

​Response

​Get source detail

​Upload a source snapshot

​Form fields

​Sync from GitHub

​Eval suggestion reviews

​Review an eval suggestion

​Request fields

​Response

​Clear an eval suggestion review

​Path parameters

​Response

​Error responses

​Example

​Apply a suggestion directly to a saved suite

​Request fields

​Response

Overview

Endpoints

List sources

Query parameters

Response

Create a source

Upload-backed source

GitHub-backed source

Response

Get source detail

Upload a source snapshot

Form fields

Sync from GitHub

Eval suggestion reviews

Review an eval suggestion

Request fields

Response

Clear an eval suggestion review

Path parameters

Response

Error responses

Example

Apply a suggestion directly to a saved suite

Request fields

Response