OpenAPI Specification
openapi: 3.0.3
info:
title: Triplit HTTP Advanced Data API
description: RESTful HTTP API for interacting with a Triplit sync server. Supports fetch, insert, bulk-insert, update, delete, delete-all, schema, stats, clear, and healthcheck operations. Authenticated via JWT Bearer tokens (Service or Anonymous tokens). Base URL follows the pattern https://<project-id>.triplit.io.
version: 1.0.0
contact:
name: Triplit
url: https://www.triplit.dev
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: https://{projectId}.triplit.io
description: Triplit Cloud sync server
variables:
projectId:
description: Your Triplit project ID
default: your-project-id
- url: http://localhost:6543
description: Local development server
security:
- BearerAuth: []
tags:
- name: Data
description: CRUD operations on collection entities
paths:
/fetch:
post:
operationId: fetchEntities
summary: Fetch entities
description: Executes a query against a collection and returns matching entities. Supports filtering, ordering, limiting, and field selection.
tags:
- Data
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- query
properties:
query:
$ref: '#/components/schemas/CollectionQuery'
example:
query:
collectionName: todos
where:
- - completed
- '='
- false
order:
- - createdAt
- DESC
limit: 10
responses:
'200':
description: Matching entities
content:
application/json:
schema:
$ref: '#/components/schemas/FetchResult'
'401':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/InternalServerError'
/insert:
post:
operationId: insertEntity
summary: Insert a single entity
description: Inserts a single entity into the specified collection.
tags:
- Data
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- collectionName
- entity
properties:
collectionName:
type: string
description: Target collection name
example: todos
entity:
$ref: '#/components/schemas/Entity'
example:
collectionName: todos
entity:
id: abc123
text: Buy groceries
completed: false
responses:
'200':
description: The inserted entity
content:
application/json:
schema:
$ref: '#/components/schemas/Entity'
'401':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/InternalServerError'
/bulk-insert:
post:
operationId: bulkInsert
summary: Bulk insert entities
description: Inserts multiple entities across one or more collections in a single transaction. Use the `noReturn` query parameter to skip returning the inserted data (faster for large imports).
tags:
- Data
parameters:
- name: noReturn
in: query
description: If true, skip returning inserted entities (improves performance for large inserts)
required: false
schema:
type: boolean
default: false
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BulkInsertBody'
responses:
'200':
description: Map of collection names to arrays of inserted entities (empty if noReturn=true)
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BulkInsertBody'
- type: object
description: Empty object when noReturn=true
'401':
$ref: '#/components/responses/Unauthorized'
'413':
description: Payload too large (default max 100 MB)
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
$ref: '#/components/responses/InternalServerError'
/bulk-insert-file:
post:
operationId: bulkInsertFile
summary: Bulk insert entities from file upload
description: Inserts multiple entities from a multipart form-data upload. The `data` field should contain the JSON payload equivalent to the bulk-insert body.
tags:
- Data
parameters:
- name: noReturn
in: query
description: If true, skip returning inserted entities
required: false
schema:
type: boolean
default: false
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
required:
- data
properties:
data:
type: string
description: JSON string of the bulk insert payload (map of collection names to entity arrays)
responses:
'200':
description: Inserted entities or empty object if noReturn=true
content:
application/json:
schema:
type: object
'400':
description: No data provided
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
$ref: '#/components/responses/Unauthorized'
/update:
post:
operationId: updateEntity
summary: Update an entity
description: Applies a partial update (patch) to an existing entity.
tags:
- Data
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- collectionName
- entityId
- changes
properties:
collectionName:
type: string
description: Collection containing the entity
example: todos
entityId:
type: string
description: ID of the entity to update
example: abc123
changes:
type: object
description: Fields to update (partial patch)
additionalProperties: true
example:
completed: true
example:
collectionName: todos
entityId: abc123
changes:
completed: true
responses:
'200':
description: Update successful
content:
application/json:
schema:
type: object
'401':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/InternalServerError'
/delete:
post:
operationId: deleteEntity
summary: Delete an entity
description: Deletes a single entity from a collection by ID.
tags:
- Data
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- collectionName
- entityId
properties:
collectionName:
type: string
description: Collection containing the entity
example: todos
entityId:
type: string
description: ID of the entity to delete
example: abc123
example:
collectionName: todos
entityId: abc123
responses:
'200':
description: Delete successful
content:
application/json:
schema:
type: object
'401':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/InternalServerError'
/delete-all:
post:
operationId: deleteAllEntities
summary: Delete all entities in a collection
description: Deletes all entities in the specified collection. Requires a service (admin) token.
tags:
- Data
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- collectionName
properties:
collectionName:
type: string
description: Collection to clear
example: todos
example:
collectionName: todos
responses:
'200':
description: All entities deleted
content:
application/json:
schema:
type: object
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
components:
responses:
Forbidden:
description: Service key (admin token) required for this operation
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
Unauthorized:
description: Missing or invalid authentication token
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
InternalServerError:
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
schemas:
BulkInsertBody:
type: object
description: Map of collection names to arrays of entities to insert
additionalProperties:
type: array
items:
$ref: '#/components/schemas/Entity'
example:
todos:
- id: '1'
text: Buy groceries
completed: false
users:
- id: u1
name: Alice
Entity:
type: object
description: A database entity (document) stored in a collection
properties:
id:
type: string
description: Unique identifier for the entity
example: abc123
additionalProperties: true
CollectionQuery:
type: object
required:
- collectionName
properties:
collectionName:
type: string
description: The name of the collection to query
example: todos
select:
type: array
description: Fields to include in the result
items:
type: string
example:
- id
- text
- completed
where:
type: array
description: Filter conditions
items:
type: array
minItems: 3
maxItems: 3
example:
- - completed
- '='
- false
order:
type: array
description: Sorting instructions
items:
type: array
minItems: 2
maxItems: 2
example:
- - createdAt
- DESC
limit:
type: integer
description: Maximum number of results to return
example: 20
after:
type: array
description: Cursor for pagination
items: {}
ErrorResponse:
type: object
properties:
name:
type: string
description: Error type name
example: TriplitError
message:
type: string
description: Human-readable error description
example: No token provided
status:
type: integer
description: HTTP status code
example: 401
FetchResult:
type: array
description: Array of matching entities
items:
$ref: '#/components/schemas/Entity'
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: JWT Bearer token. Use a Service Token (secret) for admin operations or an Anonymous token for standard user operations.