HTTP API Reference

Complete reference for Vultrino’s HTTP API endpoints.

Base URL

Default: http://127.0.0.1:7878

Authentication

API Key Authentication

Include the Vultrino API key in the Authorization header:

Authorization: Bearer vk_your_api_key_here

No Authentication (Local Mode)

In local mode without RBAC, no authentication is required.

Proxy Endpoints

Execute Proxied Request

Proxy a request through Vultrino with automatic credential injection.

URL Format:

{method} /{target_url}

Headers:

Example:

GET /https://api.github.com/user HTTP/1.1
Host: localhost:7878
X-Vultrino-Credential: github-api
Accept: application/json

Response: Returns the response from the target server, including:

• Status code
• Headers
• Body

Error Responses:

Execute API

POST /v1/execute

Execute an action with a credential. More flexible than direct proxy.

Request:

POST /v1/execute HTTP/1.1
Host: localhost:7878
Authorization: Bearer vk_xxx
Content-Type: application/json

{
  "credential": "github-api",
  "action": "http.request",
  "params": {
    "method": "GET",
    "url": "https://api.github.com/user",
    "headers": {
      "Accept": "application/json"
    },
    "body": null
  }
}

Request Fields:

Actions:

HTTP Request Params:

Response:

{
  "status": 200,
  "headers": {
    "content-type": "application/json",
    "x-ratelimit-remaining": "4999"
  },
  "body": "{\"login\":\"username\",...}"
}

Credential Management API

GET /v1/credentials

List all credentials (metadata only, no secrets).

Request:

GET /v1/credentials HTTP/1.1
Host: localhost:7878
Authorization: Bearer vk_xxx

Response:

{
  "credentials": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "alias": "github-api",
      "type": "api_key",
      "description": "GitHub personal access token",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
      "alias": "stripe-api",
      "type": "api_key",
      "description": null,
      "created_at": "2024-01-16T14:20:00Z",
      "updated_at": "2024-01-16T14:20:00Z"
    }
  ]
}

Required Permission: read

GET /v1/credentials/

Get details about a specific credential.

Request:

GET /v1/credentials/github-api HTTP/1.1
Host: localhost:7878
Authorization: Bearer vk_xxx

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "alias": "github-api",
  "type": "api_key",
  "description": "GitHub personal access token",
  "metadata": {},
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

Required Permission: read

Error Responses:

POST /v1/credentials

Create a new credential.

Request:

POST /v1/credentials HTTP/1.1
Host: localhost:7878
Authorization: Bearer vk_xxx
Content-Type: application/json

{
  "alias": "new-api-key",
  "type": "api_key",
  "data": {
    "key": "secret_key_value"
  },
  "description": "Description of this credential",
  "metadata": {
    "team": "backend"
  }
}

Request Fields:

Credential Types and Data:

api_key:

{
  "type": "api_key",
  "data": {
    "key": "your_api_key"
  }
}

basic_auth:

{
  "type": "basic_auth",
  "data": {
    "username": "user",
    "password": "pass"
  }
}

oauth2:

{
  "type": "oauth2",
  "data": {
    "client_id": "xxx",
    "client_secret": "xxx",
    "refresh_token": "xxx",
    "access_token": "xxx",
    "expires_at": "2024-02-15T10:30:00Z"
  }
}

Response:

{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "alias": "new-api-key"
}

Required Permission: write

Error Responses:

DELETE /v1/credentials/

Delete a credential.

Request:

DELETE /v1/credentials/old-api HTTP/1.1
Host: localhost:7878
Authorization: Bearer vk_xxx

Response:

{
  "success": true
}

Required Permission: delete

Error Responses:

Role Management API

GET /v1/roles

List all roles.

Request:

GET /v1/roles HTTP/1.1
Host: localhost:7878
Authorization: Bearer vk_xxx

Response:

{
  "roles": [
    {
      "id": "role-123",
      "name": "executor",
      "description": "Can execute requests",
      "permissions": ["read", "execute"],
      "credential_scopes": [],
      "created_at": "2024-01-15T10:30:00Z"
    }
  ]
}

POST /v1/roles

Create a new role.

Request:

POST /v1/roles HTTP/1.1
Host: localhost:7878
Authorization: Bearer vk_xxx
Content-Type: application/json

{
  "name": "github-reader",
  "description": "Read-only GitHub access",
  "permissions": ["read", "execute"],
  "credential_scopes": ["github-*"]
}

Response:

{
  "id": "role-456",
  "name": "github-reader"
}

DELETE /v1/roles/

Delete a role.

Request:

DELETE /v1/roles/old-role HTTP/1.1
Host: localhost:7878
Authorization: Bearer vk_xxx

Response:

{
  "success": true
}

API Key Management

GET /v1/keys

List all API keys (shows prefix only, not full key).

Request:

GET /v1/keys HTTP/1.1
Host: localhost:7878
Authorization: Bearer vk_xxx

Response:

{
  "keys": [
    {
      "id": "key-123",
      "name": "my-app",
      "key_prefix": "vk_a1b2c3d4",
      "role_id": "role-123",
      "expires_at": null,
      "last_used_at": "2024-01-16T14:20:00Z",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ]
}

POST /v1/keys

Create a new API key.

Request:

POST /v1/keys HTTP/1.1
Host: localhost:7878
Authorization: Bearer vk_xxx
Content-Type: application/json

{
  "name": "new-app-key",
  "role_id": "role-123",
  "expires_at": "2024-12-31T23:59:59Z"
}

Response:

{
  "id": "key-456",
  "key": "vk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "name": "new-app-key"
}

Note: The full key is only returned once at creation. Store it securely.

DELETE /v1/keys/

Revoke an API key.

Request:

DELETE /v1/keys/key-123 HTTP/1.1
Host: localhost:7878
Authorization: Bearer vk_xxx

Response:

{
  "success": true
}

Health Check

GET /health

Check if the server is running.

Request:

GET /health HTTP/1.1
Host: localhost:7878

Response:

{
  "status": "ok",
  "version": "0.1.0"
}

No authentication required.

Error Response Format

All errors follow this format:

{
  "error": "error_code",
  "message": "Human-readable error message",
  "details": {}
}

Common Error Codes

Rate Limits

Default rate limits (configurable):

Rate limit headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1705330800