API Reference

The Oore server exposes a REST API for managing repositories, builds, and integrations.

Base URL

http://localhost:8080/api

In production, configure BASE_URL to your public domain.

Authentication

Protected endpoints require an admin token:

Authorization: Bearer YOUR_ADMIN_TOKEN

---

Health & Status

GET /api/health

curl http://localhost:8080/api/health

{"status": "ok"}

GET /api/version

{"name": "oored", "version": "0.1.0"}

GET /api/setup/status

Requires admin token.

{
  "github": {
    "configured": true,
    "app_name": "my-oore-app",
    "installations_count": 2
  },
  "gitlab": [{
    "configured": true,
    "instance_url": "https://gitlab.com",
    "username": "myuser"
  }],
  "encryption_configured": true,
  "admin_token_configured": true
}

---

Repositories

GET /api/repositories

List all repositories.

[{
  "id": "01HNJX5Q9T3WP2V6Z8K4M7YRBF",
  "name": "my-flutter-app",
  "provider": "github",
  "owner": "myorg",
  "repo_name": "my-app",
  "clone_url": "https://github.com/myorg/my-app.git",
  "default_branch": "main",
  "is_active": true,
  "created_at": "2024-01-15T10:30:00Z"
}]

POST /api/repositories

Create a repository.

Field	Type	Required	Description
provider	string	Yes	github or gitlab
owner	string	Yes	Owner name
repo_name	string	Yes	Repository name
name	string	No	Display name
default_branch	string	No	Default: main
webhook_secret	string	No	GitLab only
github_repository_id	number	No	GitHub repository ID
github_installation_id	number	No	GitHub App installation ID
gitlab_project_id	number	No	GitLab project ID

GET /api/repositories/:id

Get a repository.

PUT /api/repositories/:id

Update a repository.

Field	Type	Required	Description
name	string	No	Display name
default_branch	string	No	Default branch
is_active	boolean	No	Active status
webhook_secret	string	No	GitLab webhook secret (re-hashed)
github_installation_id	number	No	GitHub App installation ID
gitlab_project_id	number	No	GitLab project ID

DELETE /api/repositories/:id

Delete a repository.

GET /api/repositories/:id/webhook-url

Get webhook URL for provider configuration.

GitHub

{
  "webhook_url": "https://ci.example.com/api/webhooks/github",
  "provider": "github"
}

GitLab

{
  "webhook_url": "https://ci.example.com/api/webhooks/gitlab/01HNJX...",
  "provider": "gitlab"
}

POST /api/repositories/:id/trigger

Trigger a build.

{
  "branch": "develop",
  "commit_sha": "abc1234567890"
}

Both fields are optional.

---

Builds

GET /api/builds

List builds. Optional ?repo=<ID> filter.

[{
  "id": "01HNJX9P2K4TM8Q6V5W3Y7ZRAD",
  "repository_id": "01HNJX5Q9T3WP2V6Z8K4M7YRBF",
  "commit_sha": "abc1234...",
  "branch": "main",
  "trigger_type": "webhook",
  "status": "running",
  "started_at": "2024-01-15T10:35:02Z",
  "created_at": "2024-01-15T10:35:00Z"
}]

Statuses: pending, running, success, failed, cancelled

Triggers: webhook, manual

GET /api/builds/:id

Get a build.

POST /api/builds/:id/cancel

Cancel a running build.

---

Webhooks

POST /api/webhooks/github

Receive GitHub webhooks.

Headers:

• X-Hub-Signature-256: HMAC-SHA256 signature
• X-GitHub-Event: Event type
• X-GitHub-Delivery: Delivery ID

POST /api/webhooks/gitlab/:repo_id

Receive GitLab webhooks.

Headers:

• X-Gitlab-Token: Secret token
• X-Gitlab-Event: Event type

GET /api/webhooks/events

List webhook events.

GET /api/webhooks/events/:id

Get webhook event with payload.

---

GitHub Integration

Method	Path	Auth	Description
GET	/api/github/manifest	Yes	Get manifest and creation URL
POST	/api/github/callback	Yes	Exchange code for credentials
GET	/api/github/app	Yes	Get current App configuration
DELETE	/api/github/app	Yes	Remove App credentials (requires ?force=true)
GET	/api/github/installations	Yes	List installations
POST	/api/github/sync	Yes	Sync installations and repos from GitHub

GitLab Integration

Method	Path	Auth	Description
POST	/api/gitlab/connect	Yes	Initiate OAuth flow
POST	/api/gitlab/callback	Yes	Exchange code for credentials
GET	/api/gitlab/credentials	Yes	List all credentials
DELETE	/api/gitlab/credentials/:id	Yes	Remove credentials (requires ?force=true)
GET	/api/gitlab/projects	Yes	List accessible projects
PUT	/api/gitlab/projects/:id/enabled	Yes	Enable CI for project
DELETE	/api/gitlab/projects/:id/enabled	Yes	Disable CI for project
POST	/api/gitlab/refresh	Yes	Refresh OAuth token
POST	/api/gitlab/apps	Yes	Register OAuth app for self-hosted GitLab

---

Error Responses

{"error": "Repository not found"}

Code	Description
400	Invalid request
401	Unauthorized
404	Not found
500	Server error

---

Webhook Security

GitHub

HMAC-SHA256 signature in X-Hub-Signature-256:

sha256=<hex-signature>

GitLab

Secret token in X-Gitlab-Token. Oore stores HMAC hash, not plaintext.