API Keys, REST API & Automation

Learn how to authenticate with the TurboV REST API, create scoped API keys, and automate deployments in CI/CD pipelines.

1. Creating Scoped API Keys

API keys allow automated tools, scripts, and CI/CD pipelines to interact with TurboV without sharing personal user credentials.

1. Navigate to Settings → API Keys.
2. Click Create API Key.
3. Specify a descriptive name (e.g. github-actions-deployer).
4. Select granular permission scopes:
   • applications:read / applications:write
   • deployments:create / deployments:read
   • servers:read
   • databases:read
5. (Optional) Configure an expiration date.
6. Click Generate Key.

2. Authenticating with the REST API

All API requests must include your API key in the Authorization header:

curl -X GET https://api.turbov.io/api/v1/applications \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

3. Core REST API v1 Endpoints

TurboV exposes a comprehensive RESTful API under /api/v1:

Applications & Deployments

• GET /api/v1/applications: List all applications in the organization.
• GET /api/v1/applications/:id: Fetch application details and active environments.
• POST /api/v1/deployments: Trigger a new deployment for an application environment:

  {
    "applicationId": "app_cm8...",
    "environmentId": "env_cm8...",
    "branch": "main"
  }

• GET /api/v1/deployments/:id: Fetch deployment status, commit SHA, and build logs.

Servers

• GET /api/v1/servers: List connected servers, online status, and hardware specs.
• GET /api/v1/servers/:id: Retrieve real-time CPU, RAM, and disk utilization.

Databases

• GET /api/v1/databases: List all managed database instances.
• POST /api/v1/databases/:id/actions: Execute database lifecycle actions (start, stop, restart).

4. Interactive Swagger / OpenAPI Documentation

Explore and test all endpoints interactively in your browser via the built-in Swagger UI:

https://api.turbov.io/api/v1/docs

The Swagger UI provides full JSON schemas, request/response DTOs, and a live "Try It Out" console.

5. Integrating with GitHub Actions (CI/CD)

Automate deployments when unit tests and lint checks pass in GitHub Actions:

name: Deploy to TurboV
 
on:
  push:
    branches:
      - main
 
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Code
        uses: actions/checkout@v4
 
      - name: Trigger TurboV Deployment
        run: |
          curl -X POST https://api.turbov.io/api/v1/deployments \
            -H "Authorization: Bearer ${{ secrets.TURBOV_API_KEY }}" \
            -H "Content-Type: application/json" \
            -d '{
              "applicationId": "${{ secrets.TURBOV_APP_ID }}",
              "environmentId": "${{ secrets.TURBOV_ENV_ID }}",
              "branch": "main"
            }'