REST API Reference¶

Base URL: https://api.deeplake.ai

Authentication¶

All endpoints (except /health and /ready) require a Bearer token:

Authorization: Bearer $DEEPLAKE_API_KEY

Most endpoints also require an organization ID header:

X-Activeloop-Org-Id: $DEEPLAKE_ORG_ID

Get your token from deeplake.ai under workspace settings. Store it as an environment variable:

export DEEPLAKE_API_KEY="your-token-here"
export DEEPLAKE_WORKSPACE="your-workspace"
export DEEPLAKE_ORG_ID="your-org-id"
API_URL="https://api.deeplake.ai"

Note

The DEEPLAKE_ORG_ID is the organization UUID. You can find it via the GET /organizations endpoint or from the organizations array in the GET /me response.

Health¶

Check health¶

GET /health

No authentication required.

curl -s "$API_URL/health"

Response 200

{"status": "ok"}

Check readiness¶

GET /ready

No authentication required.

curl -s "$API_URL/ready"

Response 200

{"status": "ready"}

User¶

Get current user¶

GET /me

Returns the authenticated user's profile.

curl -s "$API_URL/me" \
  -H "Authorization: Bearer $DEEPLAKE_API_KEY" \
  -H "X-Activeloop-Org-Id: $DEEPLAKE_ORG_ID"

Response 200

{
  "id": "user-abc123",
  "email": "user@example.com",
  "name": "jane.doe",
  "verified": true,
  "organizations": ["org-uuid-1", "org-uuid-2"],
  "display_name": "Jane Doe",
  "date_joined": 1717200000
}

Organizations¶

List organizations¶

GET /organizations

curl -s "$API_URL/organizations" \
  -H "Authorization: Bearer $DEEPLAKE_API_KEY" \
  -H "X-Activeloop-Org-Id: $DEEPLAKE_ORG_ID"

Response 200

[
  {"id": "my-org", "name": "My Organization", "creator": "user-uuid", "created_at": "2025-06-01T12:00:00Z"}
]

Get organization¶

GET /organizations/{org_id}

Parameter	Type	Required	Description
`org_id`	`string`	yes	Organization ID (path)

curl -s "$API_URL/organizations/$DEEPLAKE_ORG_ID" \
  -H "Authorization: Bearer $DEEPLAKE_API_KEY" \
  -H "X-Activeloop-Org-Id: $DEEPLAKE_ORG_ID"

Response 200

{
  "organization": {
    "id": "my-org",
    "name": "My Organization",
    "creator": "user-uuid",
    "created_at": "2025-06-01T12:00:00Z"
  },
  "member_count": 2,
  "pending_invites_count": 0
}

Create organization¶

POST /organizations

Parameter	Type	Required	Description
`id`	`string`	yes	Unique organization ID
`name`	`string`	yes	Display name

curl -s -X POST "$API_URL/organizations" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DEEPLAKE_API_KEY" \
  -H "X-Activeloop-Org-Id: $DEEPLAKE_ORG_ID" \
  -d '{"id": "my-org", "name": "My Organization"}'

Response 201

{"id": "my-org", "name": "My Organization"}

Update organization¶

PATCH /organizations/{org_id}

Parameter	Type	Required	Description
`org_id`	`string`	yes	Organization ID (path)
`name`	`string`	no	New display name

curl -s -X PATCH "$API_URL/organizations/$DEEPLAKE_ORG_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DEEPLAKE_API_KEY" \
  -H "X-Activeloop-Org-Id: $DEEPLAKE_ORG_ID" \
  -d '{"name": "New Name"}'

Delete organization¶

DELETE /organizations/{org_id}

curl -s -X DELETE "$API_URL/organizations/$DEEPLAKE_ORG_ID" \
  -H "Authorization: Bearer $DEEPLAKE_API_KEY" \
  -H "X-Activeloop-Org-Id: $DEEPLAKE_ORG_ID"

Response 204

No content.

List members¶

GET /organizations/{org_id}/members

curl -s "$API_URL/organizations/$DEEPLAKE_ORG_ID/members" \
  -H "Authorization: Bearer $DEEPLAKE_API_KEY" \
  -H "X-Activeloop-Org-Id: $DEEPLAKE_ORG_ID"

Response 200

{
  "members": [
    {"user_id": "user-abc", "email": "user@example.com", "role": "admin"},
    {"user_id": "user-def", "email": "other@example.com", "role": "member"}
  ],
  "total_count": 2
}

Invite member¶

POST /organizations/{org_id}/members

Parameter	Type	Required	Description
`email`	`string`	yes	Email address to invite
`role`	`string`	yes	`"admin"` or `"member"`

curl -s -X POST "$API_URL/organizations/$DEEPLAKE_ORG_ID/members" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DEEPLAKE_API_KEY" \
  -H "X-Activeloop-Org-Id: $DEEPLAKE_ORG_ID" \
  -d '{"email": "user@example.com", "role": "member"}'

Response 201

{"user_id": "user-xyz", "email": "user@example.com", "role": "member"}

Update member role¶

PATCH /organizations/{org_id}/members/{user_id}

curl -s -X PATCH "$API_URL/organizations/$DEEPLAKE_ORG_ID/members/$USER_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DEEPLAKE_API_KEY" \
  -H "X-Activeloop-Org-Id: $DEEPLAKE_ORG_ID" \
  -d '{"role": "admin"}'

Response 200

{"user_id": "user-xyz", "role": "admin"}

Remove member¶

DELETE /organizations/{org_id}/members/{user_id}

curl -s -X DELETE "$API_URL/organizations/$DEEPLAKE_ORG_ID/members/$USER_ID" \
  -H "Authorization: Bearer $DEEPLAKE_API_KEY" \
  -H "X-Activeloop-Org-Id: $DEEPLAKE_ORG_ID"

Response 204

No content.

Workspaces¶

List workspaces¶

GET /workspaces

curl -s "$API_URL/workspaces" \
  -H "Authorization: Bearer $DEEPLAKE_API_KEY" \
  -H "X-Activeloop-Org-Id: $DEEPLAKE_ORG_ID"

Response 200

{
  "data": [
    {"id": "my-workspace", "org_id": "org-uuid", "name": "My Workspace", "type": "generic", "created_at": "2025-06-01T12:00:00Z"}
  ]
}

Get workspace¶

GET /workspaces/{workspace_id}

curl -s "$API_URL/workspaces/$DEEPLAKE_WORKSPACE" \
  -H "Authorization: Bearer $DEEPLAKE_API_KEY" \
  -H "X-Activeloop-Org-Id: $DEEPLAKE_ORG_ID"

Response 200

{
  "workspace": {
    "id": "my-workspace",
    "org_id": "org-uuid",
    "name": "My Workspace",
    "type": "generic",
    "created_at": "2025-06-01T12:00:00Z"
  }
}

Create workspace¶

POST /workspaces

Parameter	Type	Required	Description
`id`	`string`	yes	Unique workspace ID (used as Postgres schema)
`name`	`string`	yes	Display name

curl -s -X POST "$API_URL/workspaces" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DEEPLAKE_API_KEY" \
  -H "X-Activeloop-Org-Id: $DEEPLAKE_ORG_ID" \
  -d '{"id": "my-workspace", "name": "My Workspace"}'

Response 201

{"id": "my-workspace", "name": "My Workspace"}

Update workspace¶

PATCH /workspaces/{workspace_id}

curl -s -X PATCH "$API_URL/workspaces/$DEEPLAKE_WORKSPACE" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DEEPLAKE_API_KEY" \
  -H "X-Activeloop-Org-Id: $DEEPLAKE_ORG_ID" \
  -d '{"name": "New Name"}'

Response 200

{"id": "my-workspace", "name": "New Name"}

Delete workspace¶

DELETE /workspaces/{workspace_id}

Warning

This permanently deletes the workspace and all its tables.

curl -s -X DELETE "$API_URL/workspaces/$DEEPLAKE_WORKSPACE" \
  -H "Authorization: Bearer $DEEPLAKE_API_KEY" \
  -H "X-Activeloop-Org-Id: $DEEPLAKE_ORG_ID"

Response 204

No content.

Tables¶

List tables¶

GET /workspaces/{workspace_id}/tables

curl -s "$API_URL/workspaces/$DEEPLAKE_WORKSPACE/tables" \
  -H "Authorization: Bearer $DEEPLAKE_API_KEY" \
  -H "X-Activeloop-Org-Id: $DEEPLAKE_ORG_ID"

Response 200

[
  {"name": "documents", "row_count": 1542},
  {"name": "images", "row_count": 328}
]

Get table details¶

GET /workspaces/{workspace_id}/tables/{table_name}

curl -s "$API_URL/workspaces/$DEEPLAKE_WORKSPACE/tables/$TABLE" \
  -H "Authorization: Bearer $DEEPLAKE_API_KEY" \
  -H "X-Activeloop-Org-Id: $DEEPLAKE_ORG_ID"

Response 200

{
  "table_name": "documents",
  "columns": [
    {"name": "id", "type": "int4", "nullable": false, "default": "nextval('documents_id_seq'::regclass)"},
    {"name": "title", "type": "text", "nullable": true, "default": null},
    {"name": "embedding", "type": "_float4", "nullable": true, "default": null}
  ],
  "row_count": 1542,
  "size_mb": 0.125
}

Create table from file¶

POST /workspaces/{workspace_id}/tables

Upload a CSV or JSON file to create a table with automatic schema inference.

Parameter	Type	Required	Description
`file`	`file`	yes	The data file (multipart form-data)
`filename`	`string`	yes	Original filename
`table_name`	`string`	yes	Target table name

curl -s -X POST "$API_URL/workspaces/$DEEPLAKE_WORKSPACE/tables" \
  -H "Authorization: Bearer $DEEPLAKE_API_KEY" \
  -H "X-Activeloop-Org-Id: $DEEPLAKE_ORG_ID" \
  -F "file=@data.csv" \
  -F "filename=data.csv" \
  -F "table_name=my_table"

Response 201

{"name": "my_table", "row_count": 245, "columns": ["col1", "col2", "col3"]}

Drop table¶

DELETE /workspaces/{workspace_id}/tables/{table_name}

curl -s -X DELETE "$API_URL/workspaces/$DEEPLAKE_WORKSPACE/tables/$TABLE" \
  -H "Authorization: Bearer $DEEPLAKE_API_KEY" \
  -H "X-Activeloop-Org-Id: $DEEPLAKE_ORG_ID"

Response 204

No content.

SQL Queries¶

The SQL endpoint is the primary interface for all data operations: CREATE TABLE, INSERT, SELECT, UPDATE, DELETE, CREATE INDEX, and DROP TABLE.

Execute query¶

POST /workspaces/{workspace_id}/tables/query

Parameter	Type	Required	Description
`query`	`string`	yes	SQL statement
`params`	`array`	no	Positional parameters for `$1`, `$2`, etc.

Schema qualification

Tables must be schema-qualified: "workspace"."table". Tables must use USING deeplake for indexes to work.

CRUD Operations¶

INSERTSELECTUPDATEDELETE

Insert a row with parameterized values. Use $1, $2, etc. for placeholders.

curl -s -X POST "$API_URL/workspaces/$DEEPLAKE_WORKSPACE/tables/query" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DEEPLAKE_API_KEY" \
  -H "X-Activeloop-Org-Id: $DEEPLAKE_ORG_ID" \
  -d '{
    "query": "INSERT INTO \"'$DEEPLAKE_WORKSPACE'\".\"documents\" (title, content, metadata) VALUES ($1, $2, $3::jsonb)",
    "params": ["First doc", "Hello world", "{\"source\": \"manual\"}"]
  }'

Response 200

{"columns": [], "rows": null, "row_count": 0, "execution_time_ms": 393.065}

Fetch rows from a table. Use LIMIT to control result size.

curl -s -X POST "$API_URL/workspaces/$DEEPLAKE_WORKSPACE/tables/query" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DEEPLAKE_API_KEY" \
  -H "X-Activeloop-Org-Id: $DEEPLAKE_ORG_ID" \
  -d '{
    "query": "SELECT * FROM \"'$DEEPLAKE_WORKSPACE'\".\"documents\" LIMIT 10"
  }'

Response 200

{
  "columns": ["id", "title", "content", "metadata", "embedding", "created_at"],
  "rows": [
    [1, "First doc", "Hello world", {"source": "manual"}, null, "2026-01-15T10:30:00Z"]
  ]
}

Modify existing rows. Combine SET with a WHERE clause.

curl -s -X POST "$API_URL/workspaces/$DEEPLAKE_WORKSPACE/tables/query" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DEEPLAKE_API_KEY" \
  -H "X-Activeloop-Org-Id: $DEEPLAKE_ORG_ID" \
  -d '{
    "query": "UPDATE \"'$DEEPLAKE_WORKSPACE'\".\"documents\" SET content = $1 WHERE title = $2",
    "params": ["Updated content", "First doc"]
  }'

Response 200

{"columns": [], "rows": null, "row_count": 0, "execution_time_ms": 420.134}

Remove rows matching a condition.

curl -s -X POST "$API_URL/workspaces/$DEEPLAKE_WORKSPACE/tables/query" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DEEPLAKE_API_KEY" \
  -H "X-Activeloop-Org-Id: $DEEPLAKE_ORG_ID" \
  -d '{
    "query": "DELETE FROM \"'$DEEPLAKE_WORKSPACE'\".\"documents\" WHERE title = $1",
    "params": ["First doc"]
  }'

Schema Operations¶

CREATE TABLECREATE INDEXDROP TABLEFull setup

Create a new table with schema definition. Always include USING deeplake at the end.

curl -s -X POST "$API_URL/workspaces/$DEEPLAKE_WORKSPACE/tables/query" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DEEPLAKE_API_KEY" \
  -H "X-Activeloop-Org-Id: $DEEPLAKE_ORG_ID" \
  -d '{
    "query": "CREATE TABLE IF NOT EXISTS \"'$DEEPLAKE_WORKSPACE'\".\"documents\" (id SERIAL PRIMARY KEY, title TEXT, content TEXT, metadata JSONB, embedding FLOAT4[], created_at TIMESTAMPTZ DEFAULT NOW()) USING deeplake"
  }'

Create a vector index for similarity search. The table must use USING deeplake.

curl -s -X POST "$API_URL/workspaces/$DEEPLAKE_WORKSPACE/tables/query" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DEEPLAKE_API_KEY" \
  -H "X-Activeloop-Org-Id: $DEEPLAKE_ORG_ID" \
  -d '{
    "query": "CREATE INDEX IF NOT EXISTS idx_vec ON \"'$DEEPLAKE_WORKSPACE'\".\"documents\" USING deeplake_index (embedding DESC)"
  }'

Permanently delete a table and all its data.

curl -s -X POST "$API_URL/workspaces/$DEEPLAKE_WORKSPACE/tables/query" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DEEPLAKE_API_KEY" \
  -H "X-Activeloop-Org-Id: $DEEPLAKE_ORG_ID" \
  -d '{
    "query": "DROP TABLE IF EXISTS \"'$DEEPLAKE_WORKSPACE'\".\"documents\""
  }'

Create a table with an embedding column, then add a vector index.

curl -s -X POST "$API_URL/workspaces/$DEEPLAKE_WORKSPACE/tables/query" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DEEPLAKE_API_KEY" \
  -H "X-Activeloop-Org-Id: $DEEPLAKE_ORG_ID" \
  -d '{
    "query": "CREATE TABLE IF NOT EXISTS \"'$DEEPLAKE_WORKSPACE'\".\"documents\" (id SERIAL PRIMARY KEY, title TEXT, content TEXT, metadata JSONB, embedding FLOAT4[], created_at TIMESTAMPTZ DEFAULT NOW()) USING deeplake"
  }'

curl -s -X POST "$API_URL/workspaces/$DEEPLAKE_WORKSPACE/tables/query" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DEEPLAKE_API_KEY" \
  -H "X-Activeloop-Org-Id: $DEEPLAKE_ORG_ID" \
  -d '{
    "query": "CREATE INDEX IF NOT EXISTS idx_vec ON \"'$DEEPLAKE_WORKSPACE'\".\"documents\" USING deeplake_index (embedding DESC)"
  }'

Advanced Queries¶

WHERE filterAggregationVector search

Filter rows by JSONB metadata fields using parameterized queries.

curl -s -X POST "$API_URL/workspaces/$DEEPLAKE_WORKSPACE/tables/query" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DEEPLAKE_API_KEY" \
  -H "X-Activeloop-Org-Id: $DEEPLAKE_ORG_ID" \
  -d '{
    "query": "SELECT id, title, content FROM \"'$DEEPLAKE_WORKSPACE'\".\"documents\" WHERE metadata->>$1 = $2 ORDER BY created_at DESC LIMIT 20",
    "params": ["source", "manual"]
  }'

Response 200

{
  "columns": ["id", "title", "content"],
  "rows": [
    [1, "First doc", "Hello world"],
    [3, "Third doc", "Another entry"]
  ]
}

Group rows and compute counts. Standard SQL aggregation functions work.

curl -s -X POST "$API_URL/workspaces/$DEEPLAKE_WORKSPACE/tables/query" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DEEPLAKE_API_KEY" \
  -H "X-Activeloop-Org-Id: $DEEPLAKE_ORG_ID" \
  -d '{
    "query": "SELECT metadata->>$1 AS source, COUNT(*) AS doc_count FROM \"'$DEEPLAKE_WORKSPACE'\".\"documents\" GROUP BY metadata->>$1 ORDER BY doc_count DESC",
    "params": ["source"]
  }'

Response 200

{
  "columns": ["source", "doc_count"],
  "rows": [
    ["manual", 15],
    ["api", 8],
    ["import", 3]
  ]
}

Find similar rows using the <#> operator. Higher score = better match.

curl -s -X POST "$API_URL/workspaces/$DEEPLAKE_WORKSPACE/tables/query" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DEEPLAKE_API_KEY" \
  -H "X-Activeloop-Org-Id: $DEEPLAKE_ORG_ID" \
  -d '{
    "query": "SELECT id, title, embedding <#> ARRAY[0.1, 0.2, 0.3]::float4[] AS score FROM \"'$DEEPLAKE_WORKSPACE'\".\"documents\" ORDER BY score DESC LIMIT 5"
  }'

Response 200

{
  "columns": ["id", "title", "score"],
  "rows": [
    [7, "Neural networks intro", 0.95],
    [3, "Deep learning basics", 0.89],
    [12, "ML fundamentals", 0.82]
  ]
}

Batch query¶

POST /workspaces/{workspace_id}/tables/query/batch

Execute the same parameterized statement with multiple sets of values. Ideal for bulk inserts.

Parameter	Type	Required	Description
`query`	`string`	yes	SQL statement with `$1`, `$2`, etc.
`params_batch`	`array[array]`	yes	Array of parameter arrays

Batch INSERTBatch UPDATEBatch DELETE

Insert multiple rows in a single request. Each entry in params_batch is one row.

curl -s -X POST "$API_URL/workspaces/$DEEPLAKE_WORKSPACE/tables/query/batch" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DEEPLAKE_API_KEY" \
  -H "X-Activeloop-Org-Id: $DEEPLAKE_ORG_ID" \
  -d '{
    "query": "INSERT INTO \"'$DEEPLAKE_WORKSPACE'\".\"documents\" (title, content) VALUES ($1, $2)",
    "params_batch": [
      ["Doc A", "Content A"],
      ["Doc B", "Content B"],
      ["Doc C", "Content C"]
    ]
  }'

Update multiple rows in one call. Each entry matches a different WHERE condition.

curl -s -X POST "$API_URL/workspaces/$DEEPLAKE_WORKSPACE/tables/query/batch" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DEEPLAKE_API_KEY" \
  -H "X-Activeloop-Org-Id: $DEEPLAKE_ORG_ID" \
  -d '{
    "query": "UPDATE \"'$DEEPLAKE_WORKSPACE'\".\"documents\" SET metadata = $1::jsonb WHERE title = $2",
    "params_batch": [
      ["{\"reviewed\": true}", "Doc A"],
      ["{\"reviewed\": true}", "Doc B"],
      ["{\"reviewed\": false}", "Doc C"]
    ]
  }'

Delete multiple rows by title in a single request.

curl -s -X POST "$API_URL/workspaces/$DEEPLAKE_WORKSPACE/tables/query/batch" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DEEPLAKE_API_KEY" \
  -H "X-Activeloop-Org-Id: $DEEPLAKE_ORG_ID" \
  -d '{
    "query": "DELETE FROM \"'$DEEPLAKE_WORKSPACE'\".\"documents\" WHERE title = $1",
    "params_batch": [
      ["Old doc A"],
      ["Old doc B"]
    ]
  }'

Eventual consistency

After INSERT, data may take a few seconds to become visible in SELECT queries. This is normal for Deeplake tables.

Endpoint Summary¶

Category	Method	Endpoint	Count
Auth	`GET`	`/me`, `/organizations`	2
Health	`GET`	`/health`, `/ready`	2
Organizations	`GET` `POST` `PATCH` `DELETE`	`/organizations/{id}`	4
Org Members	`GET` `POST` `PATCH` `DELETE`	`/organizations/{id}/members`	4
Workspaces	`GET` `POST` `PATCH` `DELETE`	`/workspaces/{id}`	5
Tables	`GET` `POST` `DELETE`	`/workspaces/{id}/tables`	4
SQL	`POST`	`/workspaces/{id}/tables/query[/batch]`	3
Total			24

Status Codes¶

Code	Meaning
`200`	Success
`201`	Created
`204`	Deleted (no content)
`400`	Bad request (invalid SQL, missing params)
`401`	Unauthorized (invalid or missing token)
`403`	Forbidden (insufficient permissions)
`404`	Not found (table, file, or workspace doesn't exist)
`409`	Conflict (table already exists without `IF NOT EXISTS`)
`500`	Internal server error