Skip to main content

API Reference

REST API documentation for BFFless.

Interactive Documentation​

Full interactive API documentation is available via Swagger UI:

The Swagger UI provides:

  • Complete endpoint documentation
  • Request/response schemas
  • Try-it-out functionality
  • Authentication testing

Base URL​

EnvironmentBase URL
Localhttp://localhost:3000
Productionhttps://admin.yourdomain.com

Authentication​

Session Authentication (Web)​

For browser-based access, use session cookies obtained from login:

Cookie: sAccessToken=...; sIdRefreshToken=...

API Key Authentication (CI/CD)​

For programmatic access, include the API key header:

X-API-Key: your-api-key

Endpoints Overview​

Authentication​

MethodEndpointAuthDescription
POST/api/auth/signupNoneRegister new user
POST/api/auth/signinNoneLogin user
POST/api/auth/signoutSessionLogout user
GET/api/auth/sessionSessionGet session info

Assets​

MethodEndpointAuthDescription
POST/api/assets/uploadAPI KeyUpload asset(s)
GET/api/assets/:idSessionGet asset metadata
DELETE/api/assets/:idSessionDelete asset

Projects​

MethodEndpointAuthDescription
GET/api/projectsSessionList projects
POST/api/projectsSessionCreate project
GET/api/projects/:idSessionGet project details
PATCH/api/projects/:idSessionUpdate project
DELETE/api/projects/:idSessionDelete project

Deployments​

MethodEndpointAuthDescription
GET/api/deploymentsSessionList deployments
POST/api/deploymentsAPI KeyCreate deployment
GET/api/deployments/:idSessionGet deployment
DELETE/api/deployments/:idSessionDelete deployment

Deployment Aliases​

MethodEndpointAuthDescription
GET/api/aliasesSessionList aliases
POST/api/aliasesSessionCreate alias
PATCH/api/aliases/:idSessionUpdate alias
DELETE/api/aliases/:idSessionDelete alias

API Keys​

MethodEndpointAuthDescription
GET/api/api-keysSessionList API keys
POST/api/api-keysSessionCreate API key
DELETE/api/api-keys/:idSessionRevoke API key

Public Access​

MethodEndpointAuthDescription
GET/public/:owner/:repo/:ref/*NoneAccess public asset
GET/repo/:owner/:repo/:sha/*OptionalAccess asset by SHA
GET/repo/:owner/:repo/alias/:alias/*OptionalAccess asset by alias

Setup​

MethodEndpointAuthDescription
GET/api/setup/statusNoneCheck setup status
POST/api/setup/completeNoneComplete initial setup

Health​

MethodEndpointAuthDescription
GET/api/healthNoneHealth check

Common Endpoints​

Upload Asset​

Upload one or more files to the platform.

POST /api/assets/upload
X-API-Key: your-api-key
Content-Type: multipart/form-data

Form Fields:

FieldTypeRequiredDescription
fileFileYesFile(s) to upload
ownerStringYesRepository owner
repoStringYesRepository name
commitShaStringYesGit commit SHA
branchStringNoGit branch name
workflowNameStringNoGitHub workflow name
workflowRunIdStringNoGitHub workflow run ID

Example (cURL):

curl -X POST https://admin.yourdomain.com/api/assets/upload \
  -H "X-API-Key: your-api-key" \
  -F "file=@screenshot.png" \
  -F "owner=myorg" \
  -F "repo=myrepo" \
  -F "commitSha=abc123def456"

Response:

{
  "success": true,
  "assets": [
    {
      "id": "uuid",
      "fileName": "screenshot.png",
      "storageKey": "myorg/myrepo/abc123def456/screenshot.png",
      "mimeType": "image/png",
      "size": 12345,
      "url": "/repo/myorg/myrepo/abc123def456/screenshot.png"
    }
  ]
}

Get Session Info​

Get information about the current authenticated user.

GET /api/auth/session
Cookie: sAccessToken=...

Response:

{
  "user": {
    "id": "uuid",
    "email": "user@example.com",
    "role": "admin"
  }
}

List Projects​

Get all projects accessible to the current user.

GET /api/projects
Cookie: sAccessToken=...

Response:

{
  "projects": [
    {
      "id": "uuid",
      "owner": "myorg",
      "name": "myrepo",
      "displayName": "My Repository",
      "isPublic": false,
      "createdAt": "2024-01-01T00:00:00Z"
    }
  ]
}

Access Public Asset​

Access a publicly available asset without authentication.

GET /repo/:owner/:repo/:sha/*path

Example:

curl https://www.yourdomain.com/repo/myorg/myrepo/abc123/coverage/index.html

Error Responses​

All errors follow a consistent format:

{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Bad Request"
}

Common Status Codes​

CodeMeaning
200Success
201Created
400Bad Request - Invalid input
401Unauthorized - Authentication required
403Forbidden - Insufficient permissions
404Not Found - Resource doesn't exist
409Conflict - Resource already exists
500Internal Server Error

Rate Limiting​

API requests may be rate-limited to prevent abuse.

  • Default: 100 requests per minute per IP
  • Upload endpoints: 10 requests per minute per API key

Rate limit headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640000000

GitHub Action Usage​

Upload assets from GitHub Actions workflows:

name: Upload Test Artifacts
on: [push]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run tests
        run: npm test

      - name: Upload coverage
        uses: bffless/ce@v1
        with:
          api-url: ${{ secrets.BFFLESS_URL }}
          api-key: ${{ secrets.BFFLESS_API_KEY }}
          files: |
            coverage/**/*.html
            test-results/**/*.png

Action Inputs​

InputRequiredDescription
api-urlYesBFFless API URL
api-keyYesAPI key for authentication
filesYesGlob patterns for files to upload
ownerNoOverride repository owner
repoNoOverride repository name
commit-shaNoOverride commit SHA
aliasNoCreate deployment alias

Pagination​

List endpoints support pagination:

GET /api/projects?page=1&limit=20

Parameters:

ParameterDefaultMaxDescription
page1-Page number (1-indexed)
limit20100Items per page

Response includes:

{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 45,
    "pages": 3
  }
}

Filtering and Sorting​

Many list endpoints support filtering and sorting:

GET /api/projects?owner=myorg&sort=createdAt&order=desc

Refer to Swagger documentation for available filters on each endpoint.