BlindInsight records API
The records API from BlindInsight — 5 operation(s) for records.
OpenAPI Specification
openapi: 3.0.3
info:
title: Blind Insight REST accounts records API
version: 10.22.0
description: End-to-end encrypted datastore
tags:
- name: records
paths:
/api/records/:
get:
operationId: records_list
description: 'List records for the given schema ID. Takes optional pagination parameters
`limit` and `offset`, as well as an optional query filter `q`.
The response will be a list of record objects.
**On the command line:**
```bash
blind records list --schema "<schema-id>"
```
#'
summary: List records
parameters:
- in: query
name: count_only
schema:
type: boolean
description: 'Return only {"count": N} without records or pagination. Useful for fetching the total count asynchronously after an initial fast query.'
- in: query
name: include_count
schema:
type: boolean
description: Deprecated. COUNT is now always included by default.
deprecated: true
- name: limit
required: false
in: query
description: Number of results to return per page.
schema:
type: integer
- name: offset
required: false
in: query
description: The initial index from which to return the results.
schema:
type: integer
- in: query
name: q
schema:
type: array
items:
type: string
description: Query filter for records.
explode: true
style: form
examples:
PhraseSearchQuery:
value: a3f1c2d4e5b6078910aabbccddeeff00=phrase:c0ffee00112233,deadbeef445566
summary: Phrase search on a text field
description: 'Use `HL=phrase:H0,H1,...,Hn` as a `q` parameter to search for a consecutive sequence of tokens in a `text: true` field. The proxy tokenises the query, derives HMACs, and builds this wire format; callers should not construct it by hand.'
- in: query
name: schema
schema:
type: string
description: The schema ID that this record belongs to.
- in: query
name: skip_count
schema:
type: boolean
description: Skip the COUNT(*) query. When true, the response omits the X-Total-Count header and the Link rel="last" header. Useful for faster responses on large result sets.
tags:
- records
security:
- cookieAuth: []
- basicAuth: []
- jwtAuth: []
responses:
'200':
headers:
X-Total-Count:
schema:
type: integer
description: Total number of records matching the query (omitted when count is skipped).
X-Query:
schema:
type: string
description: URL-encoded q parameters echoed back on filtered queries. Use this value to make a follow-up count_only request.
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedRecordList'
description: ''
post:
operationId: records_create
description: 'Create a new record with an already encrypted payload. This is the non-porcelain
endpoint. If you want to create a new record with plaintext data, use the
`record create` porcelain command or the `records ingest` command with a proxy.
The response will be the newly created record object.
**On the command line:**
```bash
blind records create --data encrypted-record.json
```'
summary: Create a new record
tags:
- records
requestBody:
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/IndexedRecord'
examples:
MultipleRecords:
value:
- - data:
2516cdf1538b273e39bf91e67abff3a0: b94f2c9129a7b95f4003afd3cb73b55e405f7c
1ca62259a4f6aeefa7c54d9b13c5650d: 695d2fe4339e50f5039cfbef464846cf202fc06
hashed_label_map:
2516cdf1538b273e39bf91e67abff3a0:
hashed_value: b4486fe169178ec73d3dfad17227da820b89d27e1994f7
field_schema:
type: string
1ca62259a4f6aeefa7c54d9b13c5650d:
hashed_value: 8d90841201a70611da0b964a743564e035fc
field_schema:
type: number
minimum: 0
maximum: 10
schema: https://demo.blindinsight.io/api/schemas/abcdef012345
summary: multiple records
RecordWithPhrase-searchableTextField:
value:
- - data:
a3f1c2d4e5b6078910aabbccddeeff00: <AES-GCM ciphertext of note field>
hashed_label_map:
a3f1c2d4e5b6078910aabbccddeeff00:
entries:
- hashed_value: c0ffee00112233
position: 0
- hashed_value: deadbeef445566
position: 1
- hashed_value: cafebabe778899
position: 2
field_schema:
type: string
text: true
schema: https://demo.blindinsight.io/api/schemas/abcdef012345
summary: Text field (phrase search)
description: 'A record whose schema contains a `text: true` string field. The proxy tokenises the plaintext, derives per-token HMACs, and sends them as `entries` instead of a single `hashed_value`. The server indexes each token''s position for later phrase queries.'
application/x-www-form-urlencoded:
schema:
type: array
items:
$ref: '#/components/schemas/IndexedRecord'
multipart/form-data:
schema:
type: array
items:
$ref: '#/components/schemas/IndexedRecord'
required: true
security:
- cookieAuth: []
- basicAuth: []
- jwtAuth: []
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/IndexedRecord'
examples:
MultipleRecords:
value:
- data:
2516cdf1538b273e39bf91e67abff3a0: 961298e17a97e7d0b847b8b743e179b2b
b92e749344f081287b034c57b7a02c77f: 695d2fe4339e50f5039cfbef464846cf202fc06
schema: https://demo.blindinsight.io/api/schemas/abcdef012345
url: https://demo.blindinsight.io/api/records/abcdef012345
owner: https://demo.blindinsight.io/api/users/abcdef012345
id: abcdef012345
summary: multiple records
description: ''
delete:
operationId: records_bulk-destroy
description: 'Delete multiple records by their IDs.
The response will be a 204 No Content if successful.
**On the command line:**
```bash
blind records bulk-destroy --id "<record-id>" --id "<record-id>"
```'
summary: Bulk delete records
parameters:
- in: query
name: id
schema:
type: array
items:
type: string
description: An array of record IDs to be deleted.
required: true
explode: true
style: form
examples:
BulkDestroy:
value:
- abcdef012345
- fedcb0987654
summary: bulk destroy
tags:
- records
security:
- cookieAuth: []
- basicAuth: []
- jwtAuth: []
responses:
'204':
description: No response body
/api/records/{id}/:
get:
operationId: records_retrieve
description: 'Retrieve a record by its ID.
The response will be the record object.
**On the command line:**
```bash
blind records retrieve --id "<record-id>"
```'
summary: Retrieve a record
parameters:
- in: path
name: id
schema:
type: string
description: A unique value identifying this record.
required: true
tags:
- records
security:
- cookieAuth: []
- basicAuth: []
- jwtAuth: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Record'
description: ''
put:
operationId: records_update
description: API for records.
summary: Update a record
parameters:
- in: path
name: id
schema:
type: string
description: A unique value identifying this record.
required: true
tags:
- records
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/RecordUpdate'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/RecordUpdate'
multipart/form-data:
schema:
$ref: '#/components/schemas/RecordUpdate'
required: true
security:
- cookieAuth: []
- basicAuth: []
- jwtAuth: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/RecordUpdate'
description: ''
patch:
operationId: records_partial_update
description: Record PATCH semantics are intentionally unsupported.
parameters:
- in: path
name: id
schema:
type: string
description: A unique value identifying this record.
required: true
tags:
- records
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PatchedRecord'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/PatchedRecord'
multipart/form-data:
schema:
$ref: '#/components/schemas/PatchedRecord'
security:
- cookieAuth: []
- basicAuth: []
- jwtAuth: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Record'
description: ''
delete:
operationId: records_destroy
description: 'Delete a record by its ID.
The response will be a 204 No Content if successful.
**On the command line:**
```bash
blind records destroy --id "<record-id>"
```'
summary: Delete a record
parameters:
- in: path
name: id
schema:
type: string
description: A unique value identifying this record.
required: true
tags:
- records
security:
- cookieAuth: []
- basicAuth: []
- jwtAuth: []
responses:
'204':
description: No response body
/api/records/decrypt/:
post:
operationId: records_decrypt
description: '[Blind Insight Proxy] Decrypt data and return records'
summary: Decrypt data and return records (only available via proxy)
tags:
- records
requestBody:
content:
application/json:
schema:
type: array
description: An array of records to be ingested.
items:
required:
- data
- schema
type: object
properties:
data:
type: object
description: The data to be encrypted and stored as a record
additionalProperties:
description: Value for the data labels
anyOf:
- type: string
- type: number
- type: integer
example:
job_function: developer
job_level: greybeard
salary: 1000
productivity: 0.95
schema:
description: The schema URL for the record
type: string
format: uri
examples:
SingleRecordDecrypt:
value:
- data:
b92e749344f081287b034c57b7a02c77f: b4486fe169178ec73d3dfad17227da820b89d27e1994f7
961298e17a97e7d0b847b8b743e179b2b: 8d90841201a70611da0b964a743564e035fc
52a1e027e31d4c5bbf126647962822fc1: 6f1374dc5a6314a36f8ef8244c
schema: https://demo.blindinsight.io/api/schemas/abcdef012345
summary: single record decrypt
application/x-www-form-urlencoded:
schema:
type: array
description: An array of records to be ingested.
items:
required:
- data
- schema
type: object
properties:
data:
type: object
description: The data to be encrypted and stored as a record
additionalProperties:
description: Value for the data labels
anyOf:
- type: string
- type: number
- type: integer
example:
job_function: developer
job_level: greybeard
salary: 1000
productivity: 0.95
schema:
description: The schema URL for the record
type: string
format: uri
multipart/form-data:
schema:
type: array
description: An array of records to be ingested.
items:
required:
- data
- schema
type: object
properties:
data:
type: object
description: The data to be encrypted and stored as a record
additionalProperties:
description: Value for the data labels
anyOf:
- type: string
- type: number
- type: integer
example:
job_function: developer
job_level: greybeard
salary: 1000
productivity: 0.95
schema:
description: The schema URL for the record
type: string
format: uri
security:
- cookieAuth: []
- basicAuth: []
- jwtAuth: []
- {}
responses:
'200':
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Record'
examples:
SingleRecordDecrypt:
value:
- data:
job_function: developer
job_level: greybeard
company: blindinsight
schema: https://demo.blindinsight.io/api/schemas/abcdef012345
url: https://demo.blindinsight.io/api/records/abcdef012345
owner: https://demo.blindinsight.io/api/users/abcdef012345
id: abcdef012345
summary: single record decrypt
description: ''
'422':
content:
application/json:
schema:
type: object
example:
detail: could not decrypt record
error: Unprocessable entity
description: Proxy decrypt failed
/api/records/ingest/:
post:
operationId: records_ingest
description: '[Blind Insight Proxy] Ingest data and encrypt it returning the encrypted records'
summary: Ingest data and encrypt it (only available via proxy)
tags:
- records
requestBody:
content:
application/json:
schema:
type: array
description: An array of records to be ingested.
items:
required:
- data
- schema
type: object
properties:
data:
type: object
description: The data to be encrypted and stored as a record
additionalProperties:
description: Value for the data labels
anyOf:
- type: string
- type: number
- type: integer
example:
job_function: developer
job_level: greybeard
salary: 1000
productivity: 0.95
schema:
description: The schema URL for the record
type: string
format: uri
examples:
ExampleRecordIngest:
value:
- data:
job_function: developer
job_level: greybeard
company: blindinsight
schema: https://demo.blindinsight.io/api/schemas/abcdef012345
- data:
name: Bob
age: 32
schema: https://demo.blindinsight.io/api/schemas/zzzxxx987654
summary: example record ingest
application/x-www-form-urlencoded:
schema:
type: array
description: An array of records to be ingested.
items:
required:
- data
- schema
type: object
properties:
data:
type: object
description: The data to be encrypted and stored as a record
additionalProperties:
description: Value for the data labels
anyOf:
- type: string
- type: number
- type: integer
example:
job_function: developer
job_level: greybeard
salary: 1000
productivity: 0.95
schema:
description: The schema URL for the record
type: string
format: uri
multipart/form-data:
schema:
type: array
description: An array of records to be ingested.
items:
required:
- data
- schema
type: object
properties:
data:
type: object
description: The data to be encrypted and stored as a record
additionalProperties:
description: Value for the data labels
anyOf:
- type: string
- type: number
- type: integer
example:
job_function: developer
job_level: greybeard
salary: 1000
productivity: 0.95
schema:
description: The schema URL for the record
type: string
format: uri
security:
- cookieAuth: []
- basicAuth: []
- jwtAuth: []
- {}
responses:
'200':
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Record'
examples:
SingleRecord:
value:
- data:
2516cdf1538b273e39bf91e67abff3a0: 961298e17a97e7d0b847b8b743e179b2b
b92e749344f081287b034c57b7a02c77f: 695d2fe4339e50f5039cfbef464846cf202fc06
schema: https://demo.blindinsight.io/api/schemas/abcdef012345
url: https://demo.blindinsight.io/api/records/abcdef012345
owner: https://demo.blindinsight.io/api/users/abcdef012345
id: abcdef012345
summary: single record
description: ''
'413':
content:
application/json:
schema:
type: object
example:
detail: max record limit of 100 exceeded
error: Request entity too large
description: Max record limit exceeded
'422':
content:
application/json:
schema:
type: object
example:
detail: could not get schema map
error: Unprocessable entity
description: Proxy ingest failed
/api/records/search/:
post:
operationId: records_search
description: '[Blind Insight Proxy] Search for records by label and value. If label or value is specified, both must be present. If neither are present, this endpoint does not filter records.'
summary: Search for records (only available via proxy)
tags:
- records
requestBody:
content:
application/json:
schema:
type: object
required:
- schema
properties:
schema:
type: string
description: Schema ID to search within
filters:
type: array
items:
type: object
properties:
label:
type: string
description: Label to search for given value
value:
type: string
description: Value to search for given label
required:
- label
- value
description: Array of label/value pairs to filter records
limit:
type: integer
description: Maximum number of records to return
offset:
type: integer
description: Number of records to skip
examples:
Search:
value:
schema: KycqdSAKzP4wUZ337b6ngb
filters:
- label: job_level
value: greybeard
limit: 10
offset: 0
summary: search
application/x-www-form-urlencoded:
schema:
type: object
required:
- schema
properties:
schema:
type: string
description: Schema ID to search within
filters:
type: array
items:
type: object
properties:
label:
type: string
description: Label to search for given value
value:
type: string
description: Value to search for given label
required:
- label
- value
description: Array of label/value pairs to filter records
limit:
type: integer
description: Maximum number of records to return
offset:
type: integer
description: Number of records to skip
multipart/form-data:
schema:
type: object
required:
- schema
properties:
schema:
type: string
description: Schema ID to search within
filters:
type: array
items:
type: object
properties:
label:
type: string
description: Label to search for given value
value:
type: string
description: Value to search for given label
required:
- label
- value
description: Array of label/value pairs to filter records
limit:
type: integer
description: Maximum number of records to return
offset:
type: integer
description: Number of records to skip
security:
- cookieAuth: []
- basicAuth: []
- jwtAuth: []
- {}
responses:
'200':
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Record'
examples:
SearchSingleRecordFound:
value:
- data:
02c77f5019095cbdef089d7e469d676daf9b9: 23056ec398be4d3dfad17227da820b89d27e1994f7
179b2b1888f4db01c8203b0be7af5c8b5b83b: 6718c4f45dd6ea0b964a743564e035fc
822fc1e33ea07ea1ddff1ec9aae93da845fee: a3f644f0c206bf8ef8244c
schema: https://demo.blindinsight.io/api/schemas/abcdef012345
summary: search single record found
description: ''
'422':
content:
application/json:
schema:
type: object
example:
detail: could not search records
error: Unprocessable entity
description: Proxy search failed
components:
schemas:
IndexedRecord:
type: object
description: Serializer for creating a Record and creating the schema index values together.
properties:
id:
type: string
readOnly: true
url:
type: string
format: uri
readOnly: true
schema:
type: string
format: uri
hashed_label_map:
type: object
example:
b92e749344f081287b034c57b7a02c77f:
hashed_value: b4486fe169178ec73d3dfad17227da820b89d27e1994f7
field_schema:
type: string
961298e17a97e7d0b847b8b743e179b2b:
hashed_value: 8d90841201a70611da0b964a743564e035fc
field_schema:
type: number
minimum: 0
maximum: 10
additionalProperties:
type: object
properties:
field_schema:
type: object
properties:
type:
type: string
minimum:
type: number
example: 0
maximum:
type: number
example: 10
required:
- type
hashed_value:
type: string
writeOnly: true
data:
type: object
description: The data that this record represents.
required:
- hashed_label_map
- id
- schema
- url
RecordUpdate:
type: object
description: Serializer for replacing a record's encrypted payload and search index.
properties:
id:
type: string
readOnly: true
url:
type: string
format: uri
readOnly: true
schema:
type: string
format: uri
data:
type: object
hashed_label_map:
type: object
example:
b92e749344f081287b034c57b7a02c77f:
hashed_value: b4486fe169178ec73d3dfad17227da820b89d27e1994f7
field_schema:
type: string
961298e17a97e7d0b847b8b743e179b2b:
hashed_value: 8d90841201a70611da0b964a743564e035fc
field_schema:
type: number
minimum: 0
maximum: 10
additionalProperties:
type: object
properties:
field_schema:
type: object
properties:
type:
type: string
minimum:
type: number
example: 0
maximum:
type: number
example: 10
required:
- type
hashed_value:
type: string
writeOnly: true
required:
- data
- hashed_label_map
- id
- schema
- url
PatchedRecord:
type: object
description: HyperlinkedModelSerializer with `id` as the first field.
properties:
id:
type: string
readOnly: true
url:
type: string
format: uri
readOnly: true
schema:
type: string
format: uri
data:
type: object
description: The data that this record represents.
PaginatedRecordList:
type: array
items:
$ref: '#/components/schemas/Record'
Record:
type: object
description: HyperlinkedModelSerializer with `id` as the first field.
properties:
id:
type: string
readOnly: true
url:
type: string
format: uri
readOnly: true
schema:
type: string
format: uri
data:
type: object
description: The data that this record represents.
required:
- id
- schema
- url
securitySchemes:
basicAuth:
type: http
scheme: basic
cookieAuth:
type: apiKey
in: cookie
name: sessionid
jwtAuth:
type: http
scheme: bearer
bearerFormat: JWT