- Authentication
- Documents Management
- POST /yorkie.v1.AdminService/CreateDocument
- POST /yorkie.v1.AdminService/UpdateDocument
- POST /yorkie.v1.AdminService/ListDocuments
- POST /yorkie.v1.AdminService/GetDocument
- POST /yorkie.v1.AdminService/GetDocuments
- POST /yorkie.v1.AdminService/RemoveDocumentByAdmin
- POST /yorkie.v1.AdminService/GetSnapshotMeta
- POST /yorkie.v1.AdminService/SearchDocuments
- YSON
Web API
Yorkie Web API allows developers to interact programmatically with their Yorkie documents without using Yorkie SDK. It is convinient for managing documents in server-side applications.
The API is implemented using Connect protocol, which means all requests are made using HTTP POST method to a specific service endpoint. The API accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes.
Base URL: https://api.yorkie.dev/yorkie.v1.AdminService/
Authentication
For APIs that require authentication, you need to add your Project SecretKey to the request's authorization header.
curl 'https://api.yorkie.dev/yorkie.v1.AdminService/ListProjects' \-H 'content-type: application/json' \-H 'authorization: PROJECT_SECRET_KEY' \--data-raw '{}'
Documents Management
POST /yorkie.v1.AdminService/CreateDocument
This endpoint creates a new document in the specified project. If initial_root
is provided, it will be used as the initial content of the document. Otherwise, an empty document will be created.
Request
Parameters:
project_name
: The name of the project.document_key
: A unique key for the new document.initial_root
: The initial root(YSON string) of the document.
curl 'https://api.yorkie.dev/yorkie.v1.AdminService/CreateDocument' \-H 'content-type: application/json' \-H 'authorization: PROJECT_SECRET_KEY' \--data-raw '{"project_name": "my-project","document_key": "document-1","initial_root": "{\"type\":\"doc\",\"content\":[]}"}'
Response
{"document": {"id": "doc_abcdef","key": "document-1","project_name": "my-project","snapshot": "{\"content\":[],\"type\":\"doc\"}","created_at": "2025-05-12T10:00:00.000Z","updated_at": "2025-05-12T10:00:00.000Z"}}
POST /yorkie.v1.AdminService/UpdateDocument
This endpoint updates the content of an existing document.
Request
Parameters:
project_name
: The name of the project.document_key
: The key of the document to update.root
: The new root content (YSON string) of the document.
curl 'https://api.yorkie.dev/yorkie.v1.AdminService/UpdateDocument' \-H 'content-type: application/json' \-H 'authorization: PROJECT_SECRET_KEY' \--data-raw '{"project_name": "my-project","document_key": "document-1","root": "{\"type\":\"doc\",\"content\":[{\"type\":\"paragraph\",\"content\":[{\"text\":\"Updated content\",\"type\":\"text\"}]}]}"}'
Response
{"document": {"id": "doc_12345","key": "document-1","project_name": "my-project","snapshot": "{\"type\":\"doc\",\"content\":[{\"type\":\"paragraph\",\"content\":[{\"text\":\"Updated content\",\"type\":\"text\"}]}]}","created_at": "2025-03-24T12:00:00.000Z","updated_at": "2025-05-12T11:30:00.000Z"}}
POST /yorkie.v1.AdminService/ListDocuments
This endpoint returns a list of documents in a project. There is a pagination mechanism to retrieve documents in batches.
You can provide the previous_id
of the last document in the previous page to get the next page of documents.
If you want to get the snapshot of the document, you can set the include_snapshot
parameter to true
.
Request
Parameters:
project_name
: The name of the project.previous_id
: The ID of the last document in the previous page. If not provided, the first page will be returned.page_size
: The number of documents to return.is_forward
: Whether to return documents in ascending order.include_snapshot
: Whether to include snapshots in the response.
curl 'https://api.yorkie.dev/yorkie.v1.AdminService/ListDocuments' \-H 'content-type: application/json' \-H 'authorization: PROJECT_SECRET_KEY' \--data-raw '{"project_name": "my-project","previous_id": "doc_last_id","page_size": 20,"is_forward": true,"include_snapshot": false}'
Response
{"documents": [{"id": "doc_12345","key": "document-1","project_name": "my-project","created_at": "2025-03-24T12:00:00.000Z","updated_at": "2025-03-24T13:00:00.000Z","snapshot": "..."},{"id": "doc_67890","key": "document-2","project_name": "my-project","created_at": "2025-03-23T10:00:00.000Z","updated_at": "2025-03-24T09:30:00.000Z","snapshot": "..."}]}
POST /yorkie.v1.AdminService/GetDocument
This endpoint returns a document by its key.
Request
Parameters:
project_name
: The name of the project.document_key
: The key of the document.
curl 'https://api.yorkie.dev/yorkie.v1.AdminService/GetDocument' \-H 'content-type: application/json' \-H 'authorization: PROJECT_SECRET_KEY' \--data-raw '{"project_name": "my-project","document_key": "document-1"}'
Response
{"document": {"id": "doc_12345","key": "document-1","project_name": "my-project","created_at": "2025-03-24T12:00:00.000Z","updated_at": "2025-03-24T13:00:00.000Z"}}
POST /yorkie.v1.AdminService/GetDocuments
Get multiple documents by their keys.
Request
Parameters:
project_name
: The name of the project.document_keys
: An array of document keys.include_snapshot
: Whether to include snapshots in the response.
curl 'https://api.yorkie.dev/yorkie.v1.AdminService/GetDocuments' \-H 'content-type: application/json' \-H 'authorization: PROJECT_SECRET_KEY' \--data-raw '{"project_name": "my-project","document_keys": ["document-1", "document-2"],"include_snapshot": false}'
Response
{"documents": [{"id": "doc_12345","key": "document-1","project_name": "my-project","created_at": "2025-03-24T12:00:00.000Z","updated_at": "2025-03-24T13:00:00.000Z"},{"id": "doc_67890","key": "document-2","project_name": "my-project","created_at": "2025-03-23T10:00:00.000Z","updated_at": "2025-03-24T09:30:00.000Z"}]}
POST /yorkie.v1.AdminService/RemoveDocumentByAdmin
Remove a document.
project_name
: The name of the project.document_key
: The key of the document.force
: Whether to force remove the document event if they are attached to clients.
Request
curl 'https://api.yorkie.dev/yorkie.v1.AdminService/RemoveDocumentByAdmin' \-H 'content-type: application/json' \-H 'authorization: PROJECT_SECRET_KEY' \--data-raw '{"project_name": "my-project","document_key": "document-1","force": false}'
Response
Empty response with success status code.
POST /yorkie.v1.AdminService/GetSnapshotMeta
Get snapshot metadata for a document.
Request
Parameters:
project_name
: The name of the project.document_key
: The key of the document.server_seq
: The server sequence number of the snapshot.
curl 'https://api.yorkie.dev/yorkie.v1.AdminService/GetSnapshotMeta' \-H 'content-type: application/json' \-H 'authorization: PROJECT_SECRET_KEY' \--data-raw '{"project_name": "my-project","document_key": "document-1","server_seq": 42}'
Response
{"snapshot": "base64-encoded-snapshot-data","lamport": 42,"version_vector": {"client1": 5,"client2": 3}}
POST /yorkie.v1.AdminService/SearchDocuments
Search for documents in a project.
Request
Parameters:
project_name
: The name of the project.query
: The prefix of the document key to search for.page_size
: The number of documents to return.
curl 'https://api.yorkie.dev/yorkie.v1.AdminService/SearchDocuments' \-H 'content-type: application/json' \-H 'authorization: PROJECT_SECRET_KEY' \--data-raw '{"project_name": "my-project","query": "search term","page_size": 20}'
Response
{"total_count": 5,"documents": [{"id": "doc_12345","key": "document-1","project_name": "my-project","created_at": "2025-03-24T12:00:00.000Z","updated_at": "2025-03-24T13:00:00.000Z"},{"id": "doc_67890","key": "document-2","project_name": "my-project","created_at": "2025-03-23T10:00:00.000Z","updated_at": "2025-03-24T09:30:00.000Z"}]}
YSON
YSON(Yorkie Structured Object Notation) is a structured data format used by Yorkie to represent documents. It is similar to JSON but extends it with additional data types optimized for collaborative editing.
Data Types
YSON supports standard JSON types and adds specialized types for collaborative applications. Each YSON type has specific use cases and representation formats:
Type | Description | Format Example | Use Case |
---|---|---|---|
String | UTF-8 encoded text | "value1" | Text content |
Number | Standard numeric value | 42.5 | Generic numeric values |
Boolean | True or false | true | Flags and boolean states |
Null | Null value | null | Absent or undefined values |
Object | Collection of key-value pairs | {"key": "value"} | Structured data |
Array | Ordered list of values | [1, 2, 3] | Sequential collections |
Int | 32-bit integer | Int(42) | Precise integer values |
Long | 64-bit integer | Long(64) | Large integer values |
Date | ISO 8601 timestamp | Date("2025-01-02T15:04:05.058Z") | Time values |
BinData | Binary data with Base64 encoding | BinData("AQID") | Binary content |
Counter | Concurrent counter | Counter(Int(10)) | Collaborative counting |
Text | List-based Rich Text | Text({"type":"p",...}) | List-based Rich Text Editor, e.g) Quill |
Tree | Tree-based Rich Text | Tree({"type":"p",...}) | Tree-based Rich Text Editor |
Custom Types Details
Int and Long
YSON provides explicit integer types to ensure consistent handling across platforms:
Int(number)
: A 32-bit integer type (-2,147,483,648 to 2,147,483,647)Long(number)
: A 64-bit integer type for larger numbers
These types help ensure that numeric values are interpreted consistently when sharing documents across different programming languages.
Date
YSON Date represents a timestamp value in ISO 8601 format:
Date("2025-01-02T15:04:05.058Z")
Dates in YSON are stored as strings in ISO format for consistent representation across systems.
BinData
Binary data in YSON is represented using Base64 encoding:
BinData("AQID") // Base64 encoded binary data
This allows binary content to be safely represented and transmitted as text.
Counter
Counter
type is specifically designed for collaborative counting operations where multiple users might modify a numeric value concurrently:
Counter(Int(10)) // A counter with initial value of 10
Using Counter instead of a regular number prevents conflicts when multiple users increment or decrement values simultaneously.
Text
The Text type is designed for rich text editing, allowing for complex formatting and attributes:
Text([{"val":"Hello","attrs":{"color":"red"}},{"val":"World","attrs":{"color":"blue"}}])
This structure allows for a list of text segments, each with its own attributes, enabling rich text editing capabilities.
Tree
The Tree type provides a specialized structure for representing hierarchical data, particularly useful for rich text editing:
Tree({"type":"p","children":[{"type":"text","value":"Tree in object"}]})
This structure allows for a tree-based representation of rich text, where each node can have its own type and attributes.
Example Document
{"str": "value1", // Standard string"num": 42 , // Standard number(float64)"int": Int(42), // 32-bit integer"long": Long(64), // 64-bit integer"null": null, // Standard null"bool": true, // Standard boolean"bytes": BinData("AQID"), // Binary data (Base64)"date": Date("2025-01-02T15:04:05.058Z"), // Date and time"counter": Counter(Int(10)), // Counter with integer value"text": Text([{"val":"Hello","attrs":{"color":"red"}},{"val":"World","attrs":{"color":"blue"}}]), // List-based Rich Text"tree": Tree({"type":"p","attrs":{"align":"center"},"children":[{"type":"text","value":"Hello World"}]}) // Tree-based Rich Text}