API reference

Overview

The Meshia REST API lets you manage sessions, experiments, and webhooks programmatically. Base URL:

https://run.meshia.io/api/v1

Authentication

All requests require an API key in the Authorization header:

curl -H "Authorization: Bearer msh_your_api_key_here" \


  https://run.meshia.io/api/v1/sessions

Generate an API key in Settings > API. Keys start with msh_. Keep them secret, they have full access to your account.

Sessions

List sessions

GET /sessions

Returns all sessions for your account, newest first. Supports ?status=running filter.

Create a session

POST /sessions

{


  "name": "llama-finetune",


  "gpu": "rtx4090",


  "repo": "github:user/repo"


}

Returns the session object with an id and status: "provisioning".

Get session

GET /sessions/:id

Stop a session

POST /sessions/:id/stop

Experiments

List experiments

GET /sessions/:id/experiments

Get experiment

GET /experiments/:id

Returns config, metrics, artifacts, and duration.

Compare experiments

POST /experiments/compare

{


  "experiment_ids": ["exp_abc", "exp_def"]


}

Returns a side-by-side comparison with config diffs and metric summaries.

Webhooks

List webhooks

GET /webhooks

Create webhook

POST /webhooks

{


  "url": "https://your-server.com/meshia-hook",


  "events": ["experiment.completed", "session.stopped"],


  "secret": "your_signing_secret"


}

Delete webhook

DELETE /webhooks/:id

Artifacts

List artifacts

GET /experiments/:id/artifacts

Download artifact

GET /artifacts/:id/download

Returns a signed URL valid for 1 hour.

Rate limits

API requests are rate-limited to 60 requests per minute per API key. If you hit the limit, you'll get a 429 Too Many Requests response with a Retry-After header.

Errors

All errors return a JSON body:

{


  "error": {


    "code": "session_not_found",


    "message": "No session with id sess_xyz exists."


  }


}

HTTP status codes follow standard conventions: 400 for bad requests, 401 for auth errors, 404 for not found, 429 for rate limits, 500 for server errors.