API to get build information

[mkg20001]

Is there any API?

Otherwise a REST for builds and a REST for the attributes per build could be useful

[roberth]

There's the API that's used by the dashboard, but I can't recommend it for other uses yet.

• subject to change
• no token management (intended for browser sessions only)

Do you have a use case in mind?

[mkg20001]

Yes.

At https://github.com/mercode-org we're building ISOs that we want to fetch from the cache to offer them as downloads on the website

I've imagined it the following way

GET /api/builds/<repo-id>?status=success&done=true

{
  "builds": [
     {
      "id": 0,
      "attributes": "/api/attributes/<build-id>",
      "state": "success|fail|evaluating|building|queued",
      "done": true/false
    }
  ],
  ...pagination metadata
}

# there should also be a /api/attributes/<build-id> with pagination to list all attributes

GET /api/attributes/<build-id>/<key>

{
  "status": "success|fail|building|queued",
  "done": true/false,
  "logs": url/null,
  "success": true/false,
  "derivation": "/nix/store/..."
}

We'd then pull the derivation from the cache

[mkg20001]

There would also need to be an accounts/orgs api and a repos api

So one could get the repo id from /api/repos/<org-id>?slug=gh_org/gh_repo | .[0].id and the org id from /api/orgs?slug=gh_org | .[0].id

[roberth]

Ok, that seems quite feasible. Looks like everything is public, so you don't have to authenticate. /jobs? lets you query up to 50 most recent jobs. You can then feed the latest successful one into /jobs/{jobId}/evaluation to find the drv path. For now, you then have to call nix-store -r to get the output path. The output path will be exposed on a new endpoint in the coming days. Also cachix has an experimental file download feature (as in not a nar), so you can build something all web-based soon if you like.

[naglalakk]

Hi I'm extremely interested about this as well. My use case is that I'm building a dashboard for having a overview of what I'm running, builds, server statistics etc so it would be very useful. I would mostly need repo name and build status. Is this on the road map? anything I can do to help?

[mkg20001]

@naglalakk You can get an overview about the apis here https://hercules-ci.com/api/v1/

These are the ones the frontend uses

There's no more documentation available than that AFAIK right now

[naglalakk]

Great thank you @mkg20001 this is enough for me now :)