BitScale API Reference

Version: 1.1.0 Base URL: https://api.bitscale.ai/api/v1 Last Updated: March 2026

Overview
Versioning
Authentication
Request & Response Format
Rate Limiting
Error Handling
Endpoints

Overview

The BitScale API allows enterprise customers to programmatically interact with their BitScale workspaces, grids, and AI enrichment pipelines. All API interactions are performed over HTTPS and return JSON-encoded responses. This reference covers authentication, request formats, error handling, and all available endpoints. If you have questions or need support, contact your dedicated BitScale account manager or reach out at team@bitscale.ai.

Versioning

The BitScale API is versioned via the URL path. The current stable version is v1.

https://api.bitscale.ai/api/v1

The API version must be included in every request URL. When a new version is released, the previous version will remain available for a deprecation window — enterprise customers will be notified in advance of any breaking changes.

Version	Status	Base URL
`v1`	✅ Current	`https://api.bitscale.ai/api/v1`

Stability guarantee: Within a given version, BitScale will not introduce breaking changes. New optional fields may be added to responses at any time and should be handled gracefully by your integration.

Authentication

All API requests must include two headers:

Header	Type	Required	Description
`api_key`	`string`	✅ Yes	Your personal API key, available from your BitScale account settings
`workspace-id`	`string`	✅ Yes	The ID of the workspace context for the request

Note: Some endpoints (such as Get Current User and List Workspaces) do not require workspace-id, as they operate at the account level.

Example headers:

GET /api/v1/user/me HTTP/1.1
Host: api.bitscale.ai
api_key: your_api_key_here
workspace-id: ws_abc123xyz
Content-Type: application/json

⚠️ Security: Never expose your API key in client-side code or public repositories. Rotate your key immediately if you suspect it has been compromised.

Request & Response Format

All request bodies must be sent as JSON with the header Content-Type: application/json
All responses are returned as JSON
Timestamps are returned in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ)
Boolean values are represented as true / false

Rate Limiting

Plan	Requests per minute
Enterprise	Contact your account manager

Rate limit details are returned in response headers:

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed per window
`X-RateLimit-Remaining`	Requests remaining in the current window
`X-RateLimit-Reset`	Unix timestamp when the window resets

Error Handling

BitScale uses standard HTTP status codes. All error responses follow this structure:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "A human-readable description of what went wrong."
  }
}

HTTP Status Codes

Status Code	Meaning
`200 OK`	Request succeeded
`201 Created`	Resource created successfully
`400 Bad Request`	Invalid request body or missing required parameters
`401 Unauthorized`	Missing or invalid `api_key`
`403 Forbidden`	Valid key, but insufficient permissions for the requested resource
`404 Not Found`	The requested resource does not exist
`422 Unprocessable Entity`	Request is well-formed but contains semantic errors
`429 Too Many Requests`	Rate limit exceeded
`500 Internal Server Error`	Unexpected server error — contact support if this persists

Common Error Codes

`error.code`	Description
`INVALID_API_KEY`	The provided `api_key` is invalid or expired
`WORKSPACE_NOT_FOUND`	No workspace found for the given ID
`GRID_NOT_FOUND`	No grid found for the given ID
`MISSING_REQUIRED_FIELD`	A required field was not provided in the request
`INVALID_COLUMN_TYPE`	An input column value does not match the expected type
`RUN_LIMIT_EXCEEDED`	Grid run quota has been reached for your plan
`INSUFFICIENT_CREDITS`	The workspace does not have enough credits to complete this run
`WEBHOOK_DELIVERY_FAILED`	The provided `webhook_url` was unreachable or returned a non-2xx response

Endpoints

1. Get Current User

Retrieves profile and account information for the authenticated user associated with the provided AiKey.

GET /user/me

Headers

Header	Required
`api_key`	✅ Yes
`workspace-id`	❌ No

Request No request body required. Response

{
  "id": "usr_abc123",
  "name": "Jane Doe",
  "email": "jane.doe@company.com",
  "avatar_url": "https://cdn.bitscale.ai/avatars/usr_abc123.png",
  "created_at": "2024-01-15T08:30:00Z",
  "plan": "enterprise"
}

Response Fields

Field	Type	Description
`id`	`string`	Unique identifier for the user
`name`	`string`	Full display name
`email`	`string`	Email address associated with the account
`avatar_url`	`string`	URL to the user’s profile image
`created_at`	`string`	ISO 8601 timestamp of account creation
`plan`	`string`	Current subscription plan

Example cURL

curl -X GET https://api.bitscale.ai/api/v1/user/me \
  -H "api_key: your_api_key_here"

2. List Workspaces

Returns a list of all workspaces the authenticated user is a member of.

GET /workspaces

Headers

Header	Required
`api_key`	✅ Yes
`workspace-id`	❌ No

Request No request body required. Response

{
  "workspaces": [
    {
      "id": "ws_abc123",
      "name": "Acme Corp — Sales",
      "role": "admin",
      "member_count": 12,
      "created_at": "2024-02-01T10:00:00Z"
    },
    {
      "id": "ws_def456",
      "name": "Acme Corp — Marketing",
      "role": "member",
      "member_count": 5,
      "created_at": "2024-03-10T14:20:00Z"
    }
  ],
  "total": 2
}

Response Fields

Field	Type	Description
`workspaces`	`array`	List of workspace objects
`workspaces[].id`	`string`	Unique workspace identifier
`workspaces[].name`	`string`	Display name of the workspace
`workspaces[].role`	`string`	Authenticated user’s role in this workspace (`admin`, `member`, etc.)
`workspaces[].member_count`	`integer`	Total number of members in the workspace
`workspaces[].created_at`	`string`	ISO 8601 creation timestamp
`total`	`integer`	Total number of workspaces returned

Example cURL

curl -X GET https://api.bitscale.ai/api/v1/workspaces \
  -H "api_key: your_api_key_here"

3. Get Workspace Details

Returns full details for a specific workspace, including its plan, credit balance, member information, and metadata.

GET /workspaces/{workspaceId}

Headers

Header	Required
`api_key`	✅ Yes
`workspace-id`	❌ No

Path Parameters

Parameter	Type	Required	Description
`workspaceId`	`string`	✅ Yes	The unique identifier of the workspace

Request No request body required. Response

{
  "id": "ws_abc123",
  "name": "Acme Corp — Sales",
  "created_at": "2024-02-01T10:00:00Z",
  "created_by": {
    "id": "usr_abc123",
    "name": "Jane Doe",
    "email": "jane.doe@company.com"
  },
  "plan": {
    "name": "Enterprise",
    "credits_included": 100000,
    "renewal_date": "2026-04-01T00:00:00Z"
  },
  "credits": {
    "total": 100000,
    "used": 34200,
    "remaining": 65800
  },
  "members": {
    "total": 12,
    "admins": 2
  }
}

Response Fields

Field	Type	Description
`id`	`string`	Unique workspace identifier
`name`	`string`	Display name of the workspace
`created_at`	`string`	ISO 8601 timestamp of workspace creation
`created_by`	`object`	Details of the user who created the workspace
`created_by.id`	`string`	User ID of the workspace creator
`created_by.name`	`string`	Full name of the workspace creator
`created_by.email`	`string`	Email address of the workspace creator
`plan`	`object`	Current subscription plan details
`plan.name`	`string`	Plan tier name (e.g., `Starter`, `Growth`, `Enterprise`)
`plan.credits_included`	`integer`	Total credits included in the current billing cycle
`plan.renewal_date`	`string`	ISO 8601 timestamp of the next billing renewal
`credits`	`object`	Credit usage summary for the current billing cycle
`credits.total`	`integer`	Total credits allocated to this workspace
`credits.used`	`integer`	Credits consumed so far in this billing cycle
`credits.remaining`	`integer`	Credits available for use
`members`	`object`	Membership summary
`members.total`	`integer`	Total number of members in the workspace
`members.admins`	`integer`	Number of members with admin role

Tip: Use this endpoint to proactively check credits.remaining before submitting large grid runs to avoid INSUFFICIENT_CREDITS errors.

Example cURL

curl -X GET "https://api.bitscale.ai/api/v1/workspaces/ws_abc123" \
  -H "api_key: your_api_key_here"

4. List Grids in a Workspace

Returns all grids within a specified workspace. Supports optional filtering by grid name.

GET /workspaces/{workspaceId}/grids

Headers

Header	Required
`api_key`	✅ Yes
`workspace-id`	✅ Yes

Path Parameters

Parameter	Type	Required	Description
`workspaceId`	`string`	✅ Yes	The unique identifier of the workspace

Query Parameters

Parameter	Type	Required	Description
`search`	`string`	❌ No	Filter grids by name (case-insensitive, partial match supported)

Request No request body required. Response

{
  "grids": [
    {
      "id": "grid_001",
      "name": "Lead Enrichment — Q1",
      "description": "Enriches inbound leads with company and contact data.",
      "row_count": 1500,
      "column_count": 12,
      "created_at": "2024-04-01T09:00:00Z",
      "updated_at": "2024-04-15T11:30:00Z"
    }
  ],
  "total": 1
}

Response Fields

Field	Type	Description
`grids`	`array`	List of grid objects
`grids[].id`	`string`	Unique grid identifier
`grids[].name`	`string`	Display name of the grid
`grids[].description`	`string`	Optional description of the grid’s purpose
`grids[].row_count`	`integer`	Total number of rows in the grid
`grids[].column_count`	`integer`	Total number of columns in the grid
`grids[].created_at`	`string`	ISO 8601 creation timestamp
`grids[].updated_at`	`string`	ISO 8601 timestamp of last modification
`total`	`integer`	Total number of matching grids

Example cURL

# List all grids
curl -X GET "https://api.bitscale.ai/api/v1/workspaces/ws_abc123/grids" \
  -H "api_key: your_api_key_here" \
  -H "workspace-id: ws_abc123"

# Search by name
curl -X GET "https://api.bitscale.ai/api/v1/workspaces/ws_abc123/grids?search=lead" \
  -H "api_key: your_api_key_here" \
  -H "workspace-id: ws_abc123"

5. Get Grid Details

Returns full metadata for a specific grid, including all column definitions, their types, and grid-level settings.

GET /grids/{gridId}

Headers

Header	Required
`api_key`	✅ Yes
`workspace-id`	✅ Yes

Path Parameters

Parameter	Type	Required	Description
`gridId`	`string`	✅ Yes	The unique identifier of the grid

Request No request body required. Response

{
  "id": "grid_001",
  "name": "Lead Enrichment — Q1",
  "description": "Enriches inbound leads with company and contact data.",
  "settings": {
    "row_limit": 5000,
    "auto_run": false,
    "visibility": "workspace"
  },
  "columns": [
    {
      "id": "3f7a1c2e-9b4d-4e8f-a012-bc3d56ef7890",
      "name": "Full Name",
      "type": "text",
      "is_input": true,
      "is_output": false,
      "required": true
    },
    {
      "id": "7c2b0f4a-1d3e-4a9c-b567-de8f90ab1234",
      "name": "Company",
      "type": "text",
      "is_input": true,
      "is_output": false,
      "required": false
    },
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Enriched Email",
      "type": "ai_enrichment",
      "is_input": false,
      "is_output": true,
      "required": false
    }
  ],
  "row_count": 1500,
  "created_at": "2024-04-01T09:00:00Z",
  "updated_at": "2024-04-15T11:30:00Z"
}

Response Fields

Field	Type	Description
`id`	`string`	Unique grid identifier
`name`	`string`	Display name of the grid
`description`	`string`	Description of the grid’s purpose
`settings`	`object`	Grid-level configuration (see below)
`settings.row_limit`	`integer`	Maximum number of rows the grid can hold
`settings.auto_run`	`boolean`	Whether the grid runs automatically on new row insertion
`settings.visibility`	`string`	Access scope: `workspace`, `private`, or `public`
`columns`	`array`	Ordered list of column definitions
`columns[].id`	`string`	Unique column UUID — use this as the key in `inputs` and `output_columns` when calling Run a Grid
`columns[].name`	`string`	Human-readable column name
`columns[].type`	`string`	Column data type (see Column Types below)
`columns[].is_input`	`boolean`	Whether this column accepts input when running the grid
`columns[].is_output`	`boolean`	Whether this column produces AI-enriched output
`columns[].required`	`boolean`	Whether this column must be provided when running the grid
`row_count`	`integer`	Total number of rows currently in the grid
`created_at`	`string`	ISO 8601 creation timestamp
`updated_at`	`string`	ISO 8601 timestamp of last modification

Column Types

Type	Description
`text`	Plain text string
`number`	Numeric value (integer or float)
`url`	A valid URL string
`email`	An email address string
`date`	ISO 8601 date string
`boolean`	`true` or `false`
`ai_enrichment`	Output column populated by a BitScale AI agent
`formula`	Computed column derived from other column values

Example cURL

curl -X GET "https://api.bitscale.ai/api/v1/grids/grid_001" \
  -H "api_key: your_api_key_here" \
  -H "workspace-id: ws_abc123"

6. Run a Grid

Executes a grid with the provided input column values and returns enriched output. Supports both synchronous and asynchronous execution modes.

POST /grids/{gridId}/run

Headers

Header	Required
`api_key`	✅ Yes
`workspace-id`	✅ Yes
`Content-Type`	✅ Yes — must be `application/json`

Path Parameters

Parameter	Type	Required	Description
`gridId`	`string`	✅ Yes	The unique identifier of the grid to run

Request Body

{
  "mode": "async",
  "inputs": {
    "3f7a1c2e-9b4d-4e8f-a012-bc3d56ef7890": "Jane Doe",
    "7c2b0f4a-1d3e-4a9c-b567-de8f90ab1234": "Acme Corp"
  },
  "output_columns": [
    "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "b2c3d4e5-f6a7-8901-bcde-f12345678901"
  ],
  "webhook_url": "https://your-server.com/webhooks/bitscale"
}

Request Fields

Field	Type	Required	Description
`mode`	`string`	❌ No	Execution mode: `sync` (default) or `async`
`inputs`	`object`	✅ Yes	Key-value pairs mapping column UUIDs to their input values. Column UUIDs can be found in the `columns[].id` field via Get Grid Details
`output_columns`	`array of strings`	❌ No	List of column UUIDs to include in the response. If omitted, all columns are returned as key-value pairs
`webhook_url`	`string`	❌ No	(async only) A publicly accessible HTTPS URL. BitScale will POST the completed run result to this URL when execution finishes. Ignored in `sync` mode

Synchronous Response (`mode: "sync"`)

The API processes the row and returns the result directly.

{
  "mode": "sync",
  "status": "completed",
  "outputs": {
    "3f7a1c2e-9b4d-4e8f-a012-bc3d56ef7890": "Jane Doe",
    "7c2b0f4a-1d3e-4a9c-b567-de8f90ab1234": "Acme Corp",
    "a1b2c3d4-e5f6-7890-abcd-ef1234567890": "jane.doe@acmecorp.com",
    "b2c3d4e5-f6a7-8901-bcde-f12345678901": "https://linkedin.com/in/janedoe"
  },
  "credits": {
    "consumed": 12,
    "remaining": 65788
  }
}

Asynchronous Response (`mode: "async"`)

The API immediately returns a run ID. Use the run ID to poll for results, or provide a webhook_url to receive a callback when the run completes.

{
  "mode": "async",
  "run_id": "run_xyz789",
  "status": "queued",
  "poll_url": "https://api.bitscale.ai/api/v1/grids/grid_001/runs/run_xyz789"
}

Polling for Results

GET /grids/{gridId}/runs/{runId}

Poll the poll_url until status is completed or failed.

{
  "run_id": "run_xyz789",
  "status": "completed",
  "outputs": {
    "3f7a1c2e-9b4d-4e8f-a012-bc3d56ef7890": "Jane Doe",
    "7c2b0f4a-1d3e-4a9c-b567-de8f90ab1234": "Acme Corp",
    "a1b2c3d4-e5f6-7890-abcd-ef1234567890": "jane.doe@acmecorp.com",
    "b2c3d4e5-f6a7-8901-bcde-f12345678901": "https://linkedin.com/in/janedoe"
  },
  "credits": {
    "consumed": 12,
    "remaining": 65788
  },
  "started_at": "2024-04-15T12:00:00Z",
  "completed_at": "2024-04-15T12:00:04Z"
}

Run Status Values

Status	Description
`queued`	Run has been accepted and is waiting to be processed
`running`	Run is currently being executed
`completed`	Run finished successfully — outputs are available
`failed`	Run encountered an error — check `error` field for details

Webhook Delivery If a webhook_url was provided in the request, BitScale will send an HTTP POST request to that URL upon run completion (whether completed or failed). The webhook payload is identical to the poll response.

⚠️ Requirements: The webhook_url must be a publicly accessible https:// endpoint. BitScale does not support http:// or localhost URLs for webhook delivery.

Your endpoint must respond with a 2xx status code within 10 seconds to acknowledge receipt. If delivery fails, BitScale will retry up to 3 times with exponential backoff. Webhook Payload Example

{
  "run_id": "run_xyz789",
  "grid_id": "grid_001",
  "status": "completed",
  "outputs": {
    "3f7a1c2e-9b4d-4e8f-a012-bc3d56ef7890": "Jane Doe",
    "7c2b0f4a-1d3e-4a9c-b567-de8f90ab1234": "Acme Corp",
    "a1b2c3d4-e5f6-7890-abcd-ef1234567890": "jane.doe@acmecorp.com",
    "b2c3d4e5-f6a7-8901-bcde-f12345678901": "https://linkedin.com/in/janedoe"
  },
  "credits": {
    "consumed": 12,
    "remaining": 65788
  },
  "started_at": "2024-04-15T12:00:00Z",
  "completed_at": "2024-04-15T12:00:04Z"
}

Webhook Headers Sent by BitScale

Header	Description
`Content-Type`	`application/json`
`X-BitScale-Run-Id`	The `run_id` of the completed run
`X-BitScale-Signature`	HMAC-SHA256 signature of the payload, for verifying authenticity

Response Fields

Field	Type	Description
`mode`	`string`	Execution mode used: `sync` or `async`
`status`	`string`	Current run status
`run_id`	`string`	(async only) Unique identifier for the run
`poll_url`	`string`	(async only) URL to poll for run status and results
`outputs`	`object`	Key-value pairs of column IDs and their values (present when `status` is `completed`)
`credits`	`object`	Credit usage for this run (present when `status` is `completed`)
`credits.consumed`	`integer`	Number of credits deducted for this run
`credits.remaining`	`integer`	Credits remaining in the workspace after this run
`started_at`	`string`	(async only) ISO 8601 timestamp when execution began
`completed_at`	`string`	(async only) ISO 8601 timestamp when execution finished

Example cURL — Synchronous

curl -X POST "https://api.bitscale.ai/api/v1/grids/grid_001/run" \
  -H "api_key: your_api_key_here" \
  -H "workspace-id: ws_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "sync",
    "inputs": {
      "3f7a1c2e-9b4d-4e8f-a012-bc3d56ef7890": "Jane Doe",
      "7c2b0f4a-1d3e-4a9c-b567-de8f90ab1234": "Acme Corp"
    },
    "output_columns": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"]
  }'

Example cURL — Asynchronous

# Step 1: Submit the run (with optional webhook)
curl -X POST "https://api.bitscale.ai/api/v1/grids/grid_001/run" \
  -H "api_key: your_api_key_here" \
  -H "workspace-id: ws_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "async",
    "inputs": {
      "3f7a1c2e-9b4d-4e8f-a012-bc3d56ef7890": "Jane Doe",
      "7c2b0f4a-1d3e-4a9c-b567-de8f90ab1234": "Acme Corp"
    },
    "webhook_url": "https://your-server.com/webhooks/bitscale"
  }'

# Step 2: Poll for results
curl -X GET "https://api.bitscale.ai/api/v1/grids/grid_001/runs/run_xyz789" \
  -H "api_key: your_api_key_here" \
  -H "workspace-id: ws_abc123"

Changelog

Version	Date	Notes
1.1.0	March 2026	Added Get Workspace Details endpoint; added `webhook_url` support for async grid runs; added `credits` object to run responses; introduced URL-based API versioning (`/v1`)
1.0.0	March 2026	Initial release

For enterprise support, contact your BitScale account manager or email team@bitscale.ai.

Get Started

Basics

Advanced

Tutorials

Playbook

Ingredients

BitScale API Reference

Table of Contents

Overview

Versioning

Authentication

Request & Response Format

Rate Limiting

Error Handling

HTTP Status Codes

Common Error Codes

Endpoints

1. Get Current User

2. List Workspaces

3. Get Workspace Details

4. List Grids in a Workspace

5. Get Grid Details

6. Run a Grid

Request Body

Synchronous Response (`mode: "sync"`)

Asynchronous Response (`mode: "async"`)

Changelog

Get Started

Basics

Advanced

Tutorials

Playbook

Ingredients

​Table of Contents

​Overview

​Versioning

​Authentication

​Request & Response Format

​Rate Limiting

​Error Handling

​HTTP Status Codes

​Common Error Codes

​Endpoints

​1. Get Current User

​2. List Workspaces

​3. Get Workspace Details

​4. List Grids in a Workspace

​5. Get Grid Details

​6. Run a Grid

​Request Body

​Synchronous Response (mode: "sync")

​Asynchronous Response (mode: "async")

​Changelog

Table of Contents

Overview

Versioning

Authentication

Request & Response Format

Rate Limiting

Error Handling

HTTP Status Codes

Common Error Codes

Endpoints

1. Get Current User

2. List Workspaces

3. Get Workspace Details

4. List Grids in a Workspace

5. Get Grid Details

6. Run a Grid

Request Body

Synchronous Response (`mode: "sync"`)

Asynchronous Response (`mode: "async"`)

Changelog