API Reference¶

The Blind Insight REST API is an end-to-end encrypted datastore. All data is encrypted before it reaches Blind Insight's servers — the API stores and retrieves ciphertext. Plaintext never transits the network to or from the API.

Current API version: 10.12.0

Base URL¶

https://api.app.blindinsight.io

All endpoints are relative to this base URL. For the demo environment, use https://api.demo.blindinsight.io.

Authentication¶

The API supports three authentication methods. See Authentication for full details.

Method	Header	When to use
Basic Auth	`Authorization: Basic <base64(email:password)>`	Simple scripts, testing
JWT Bearer	`Authorization: Bearer <access_token>`	Production applications
Cookie	`Cookie: sessionid=<session_id>`	Browser-based access

Request Format¶

All request and response bodies use JSON. Set Content-Type: application/json on write requests.

POST /api/datasets/ HTTP/2
Host: api.app.blindinsight.io
Authorization: Bearer <token>
Content-Type: application/json

{"name": "My Dataset", "organization": "/api/organizations/<id>/"}

Response Format¶

Successful responses return the created or updated object. List endpoints return a paginated envelope:

{
  "count": 42,
  "next": "https://api.app.blindinsight.io/api/datasets/?page=2",
  "previous": null,
  "results": [...]
}

IDs and Object References¶

Blind Insight uses short string IDs (e.g. FWaw3Gr7Gmv8xg8mpuabn7). When referencing related objects in request bodies, use the full URL path — not the bare ID:

{
  "dataset": "/api/datasets/FWaw3Gr7Gmv8xg8mpuabn7/",
  "schema": "/api/schemas/iKi3YbiG7Ax9cEZ7YPVNgw/"
}

Proxy-Only Endpoints¶

Several endpoints are only available when requests are routed through a running Blind Proxy. The Proxy encrypts or decrypts data locally before forwarding it to the API — plaintext never reaches the server.

Endpoint	Description
`POST /api/records/ingest/`	Encrypt and ingest records
`POST /api/records/search/`	Encrypted search
`POST /api/records/decrypt/`	Decrypt records
`POST /api/schemas/decrypt/`	Decrypt a schema
`POST /api/jobs/upload/`	Batch upload
`POST /api/files/`	TUS resumable upload

Error Codes¶

Code	Meaning
`200 OK`	Request succeeded
`201 Created`	Object created
`204 No Content`	Deleted successfully
`400 Bad Request`	Validation error — check request body
`401 Unauthorized`	Missing or invalid credentials
`403 Forbidden`	Authenticated but not authorized
`404 Not Found`	Object does not exist

Error responses include a detail message:

{ "detail": "Authentication credentials were not provided." }

Validation errors return field-level detail:

{
  "name": ["This field is required."],
  "organization": ["Invalid hyperlink — No URL conf matches the given path."]
}

Resources¶

Datasets¶

Datasets group schemas. Think of a dataset as a database.

Method	Path	Description
`GET`	`/api/datasets/`	List datasets
`POST`	`/api/datasets/`	Create a dataset
`GET`	`/api/datasets/{id}/`	Get a dataset
`PUT`	`/api/datasets/{id}/`	Update a dataset
`PATCH`	`/api/datasets/{id}/`	Partially update a dataset
`DELETE`	`/api/datasets/{id}/`	Delete a dataset
`GET`	`/api/datasets/{id}/schema/{slug}/`	Get a schema by slug

Create a dataset

POST /api/datasets/ HTTP/2
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Business Data",
  "organization": "/api/organizations/<org_id>/",
  "description": "Production customer records"
}

{
  "id": "FWaw3Gr7Gmv8xg8mpuabn7",
  "url": "/api/datasets/FWaw3Gr7Gmv8xg8mpuabn7/",
  "organization": "/api/organizations/jSzAcLbFkDSCtFipdmLM3S/",
  "name": "Business Data",
  "slug": "business-data",
  "description": "Production customer records"
}

Schemas¶

Schemas define the shape of your data using JSON Schema. Think of a schema as a table. Only object types are supported. Field types are limited to string, integer, and number. Numeric fields require minimum and maximum; number fields also require precision.

See Defining Schemas for a full guide with examples.

Method	Path	Description
`GET`	`/api/schemas/`	List schemas
`POST`	`/api/schemas/`	Create a schema
`GET`	`/api/schemas/{id}/`	Get a schema
`PUT`	`/api/schemas/{id}/`	Update a schema
`PATCH`	`/api/schemas/{id}/`	Partially update a schema
`DELETE`	`/api/schemas/{id}/`	Delete a schema
`GET`	`/api/schemas/{id}/teams/`	List teams for a schema
`POST`	`/api/schemas/decrypt/`	Decrypt a schema (proxy-only)

Records¶

Records are rows of data that conform to a schema. Each field is encrypted using a key derived from the schema. Direct record creation via the API stores raw (unencrypted) data — always use the Blind Proxy's ingest endpoint to create encrypted records.

See Ingesting Records for a full guide.

Method	Path	Description
`GET`	`/api/records/`	List records
`GET`	`/api/records/{id}/`	Get a record
`DELETE`	`/api/records/{id}/`	Delete a record
`DELETE`	`/api/records/`	Bulk delete records
`POST`	`/api/records/ingest/`	Encrypt and ingest records (proxy-only)
`POST`	`/api/records/search/`	Encrypted search (proxy-only)
`POST`	`/api/records/decrypt/`	Decrypt records (proxy-only)

Organizations¶

Organizations are isolated accounts. All objects belong to an organization. Every organization has one owner and can have multiple admins and users.

Method	Path	Description
`GET`	`/api/organizations/`	List organizations
`POST`	`/api/organizations/`	Create an organization
`GET`	`/api/organizations/{id}/`	Get an organization
`PUT`	`/api/organizations/{id}/`	Update an organization
`DELETE`	`/api/organizations/{id}/`	Delete an organization
`GET`	`/api/organizations/by-slug/{slug}/`	Get an organization by slug
`GET`	`/api/organizations/{id}/owner/`	Get the organization owner
`GET`	`/api/organizations/{id}/users/`	List organization users
`POST`	`/api/organizations/{id}/users/`	Add a user to an organization
`GET`	`/api/organizations/{org_id}/invitations/`	List invitations
`POST`	`/api/organizations/{org_id}/invitations/`	Invite a user
`GET`	`/api/organizations/{org_id}/teams/`	List teams
`POST`	`/api/organizations/{org_id}/teams/`	Create a team
`POST`	`/api/organizations/{org_id}/teams/{id}/add_member/`	Add a team member
`POST`	`/api/organizations/{org_id}/teams/{id}/remove_member/`	Remove a team member
`GET`	`/api/organizations/{org_id}/audit-logs/`	List audit log entries

Users¶

Method	Path	Description
`GET`	`/api/users/self/`	Get the current user
`GET`	`/api/users/{id}/`	Get a user
`GET`	`/api/users/by_name/{email}/`	Look up a user by email
`PUT`	`/api/users/{id}/`	Update a user
`DELETE`	`/api/users/{id}/`	Delete a user

Key sharing allows Data Owners to grant access to encrypted data without exposing plaintext keys. It involves five resources that work together.

See Key Sharing for a conceptual overview and CLI walkthrough.

Identities — PGP key pairs registered per user per device. Required before a user can be added to a team.

Method	Path	Description
`GET`	`/api/identities/`	List identities
`POST`	`/api/identities/`	Register an identity
`GET`	`/api/identities/{id}/`	Get an identity
`DELETE`	`/api/identities/{id}/`	Delete an identity

Grants — Define field-level access permissions for a team on a schema.

Method	Path	Description
`GET`	`/api/grants/`	List grants
`POST`	`/api/grants/`	Create a grant
`GET`	`/api/grants/{id}/`	Get a grant
`PUT`	`/api/grants/{id}/`	Update a grant
`DELETE`	`/api/grants/{id}/`	Delete a grant

Requests — Created automatically when a user is added to a team. Represent a pending request for key material.

Method	Path	Description
`GET`	`/api/requests/`	List requests
`GET`	`/api/requests/{id}/`	Get a request
`POST`	`/api/requests/{id}/fulfill/`	Fulfill a single request
`POST`	`/api/requests/fulfill/`	Fulfill all outstanding requests

Materials — Encrypted key payloads that satisfy requests.

Method	Path	Description
`GET`	`/api/materials/`	List materials
`POST`	`/api/materials/receive/`	Receive all outstanding materials
`POST`	`/api/materials/{id}/receive/`	Receive a single material
`POST`	`/api/materials/{id}/proof/`	Submit proof of receipt
`GET`	`/api/materials/overrides/`	List key overrides
`DELETE`	`/api/materials/overrides/`	Delete all key overrides
`DELETE`	`/api/materials/overrides/{key}/`	Delete a specific key override

Batch Jobs¶

Method	Path	Description
`POST`	`/api/jobs/upload/`	Start a batch upload job (proxy-only)
`GET`	`/api/jobs/{job_id}/`	Get job status (proxy-only)
`GET`	`/api/ws/jobs/{job_id}/`	Connect to job status websocket (proxy-only)
`GET`	`/api/delete-jobs/{job_id}/`	Get async delete job status
`POST`	`/api/files/`	Create TUS upload resource (proxy-only)
`PATCH`	`/api/files/{id}/`	Upload file chunk (proxy-only)
`DELETE`	`/api/files/{id}/`	Cancel an upload (proxy-only)

Status¶

GET /api/status/ HTTP/2

Returns 200 OK when the API is healthy. No authentication required.

Interactive Explorer¶

For an interactive reference where you can authenticate and make live API calls:

Open Interactive API Explorer