GitBlixt
Docs Navigation

REST API

GitBlixt implements the GitLab REST API v4 under /api/v4. The goal is compatibility: tools built for GitLab — CI runners, CodeRabbit, the glab CLI, custom scripts — can point at your GitBlixt instance and work without changes. Endpoints return GitLab-shaped JSON.

The base URL for every request is https://git.vianet.us/api/v4.

Authentication

Most endpoints require authentication. Create a token on the Personal Access Tokens page (tokens are prefixed with glpat-) and send it on every request. GitBlixt accepts the token two ways, matching GitLab:

As a Bearer token in the Authorization header:

curl -H "Authorization: Bearer glpat-YOUR_TOKEN" \
  https://#git.vianet.us/api/v4/user

Or in the GitLab-style PRIVATE-TOKEN header:

curl -H "PRIVATE-TOKEN: glpat-YOUR_TOKEN" \
  https://#git.vianet.us/api/v4/user

Requests without a valid token are treated as anonymous. Endpoints that require authentication respond with 401 and a body of {"error": "unauthorized"}. Token scopes (api, read_api, read_repository, write_repository) determine what an authenticated token may do.

Project IDs

Anywhere the API expects a project :id, you may pass either of two forms:

  • The numeric project ID, e.g. 42
  • The URL-encoded namespace/repo path, e.g. alice%2Fwebsite (the / must be encoded as %2F)

These two requests are equivalent:

curl -H "PRIVATE-TOKEN: glpat-YOUR_TOKEN" \
  https://#git.vianet.us/api/v4/projects/42

curl -H "PRIVATE-TOKEN: glpat-YOUR_TOKEN" \
  https://#git.vianet.us/api/v4/projects/alice%2Fwebsite

In project JSON the id is always the integer ID; the path is exposed separately as path_with_namespace.

Pagination

List endpoints are paginated with two query parameters:

  • page — page number, starting at 1 (default 1)
  • per_page — results per page (default 20, maximum 100)

Responses carry the current paging position in the X-Page and X-Per-Page headers. 

curl -i -H "PRIVATE-TOKEN: glpat-YOUR_TOKEN" \
  "https://#git.vianet.us/api/v4/projects?page=2&per_page=50"

Errors

Errors return the appropriate HTTP status with a JSON body. Most errors use a message key; authentication failures use an error key.

Status Meaning Example body
401 Missing or invalid token {"error": "unauthorized"}
403 Authenticated but not permitted {"message": "Forbidden"}
404 Resource not found {"message": "404 Project Not Found"}
422 Validation failed {"message": {"title": ["can't be blank"]}}

Endpoint Reference

The following groups are implemented. Project-scoped routes take a project :id as described above; issue, merge request, and pipeline routes take the internal ID (iid) within that project.

Group Endpoints
Users GET /user, GET /users, GET /users/:id, GET/POST/DELETE /user/keys
Groups & namespaces GET /namespaces, GET/POST /groups, GET /groups/:id, GET/POST /groups/:id/members
Projects GET/POST /projects, GET/PUT/DELETE /projects/:id, POST /projects/:id/star & /unstar
Repository /projects/:id/repository/branches, /commits, /tree, /compare, /files/:path
Merge requests GET/POST /projects/:id/merge_requests, GET/PUT .../:iid, PUT .../:iid/merge, .../notes, .../discussions, .../changes, .../commits
Issues GET/POST /projects/:id/issues, GET/PUT .../:iid, GET/POST .../:iid/notes
Labels GET/POST /projects/:id/labels, PUT/DELETE .../:label_id
Milestones GET/POST /projects/:id/milestones, GET/PUT/DELETE .../:milestone_id
Releases GET/POST /projects/:id/releases, GET/DELETE .../:tag_name
Pipelines & jobs GET /projects/:id/pipelines, GET .../:pipeline_id, GET .../:pipeline_id/jobs, GET/POST/PUT/DELETE /projects/:id/variables
Protected branches GET/POST /projects/:id/protected_branches, GET/DELETE .../:name
Webhooks GET/POST /projects/:id/hooks, DELETE .../:hook_id
Scheduled agents (GitBlixt) GET/POST /projects/:id/scheduled_agents, GET/PUT/DELETE .../:id, POST .../:id/run
Events & notifications GET /events, GET /projects/:id/events, GET /notifications, POST /notifications/:id/mark_as_read, POST /notifications/mark_all_as_read

Examples

List your projects:

curl -H "PRIVATE-TOKEN: glpat-YOUR_TOKEN" \
  https://#git.vianet.us/api/v4/projects

Fetch a single project by path:

curl -H "PRIVATE-TOKEN: glpat-YOUR_TOKEN" \
  https://#git.vianet.us/api/v4/projects/alice%2Fwebsite

Create an issue. The title is required; description, assignee_id, and labels are optional: 

curl -X POST \
  -H "PRIVATE-TOKEN: glpat-YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "Login button is misaligned", "description": "On mobile the button overflows."}' \
https://#git.vianet.us/api/v4/projects/alice%2Fwebsite/issues

Create a scheduled agent (a GitBlixt-specific endpoint). The run authenticates with the AI provider key of the user whose token creates it; only the repository owner may manage agents: 

curl -X POST \
  -H "PRIVATE-TOKEN: glpat-YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Update deps", "cron": "0 9 1 * *", "prompt": "Bump dependencies and open an MR.", "provider": "anthropic", "model": "claude-opus-4-8"}' \
https://#git.vianet.us/api/v4/projects/alice%2Fwebsite/scheduled_agents

Trigger a run immediately (returns the queued AI job id):

curl -X POST -H "PRIVATE-TOKEN: glpat-YOUR_TOKEN" \
  https://#git.vianet.us/api/v4/projects/alice%2Fwebsite/scheduled_agents/1/run