Yorkie

If you want to update this page or add new content, please submit a pull request to the Homepage.

Admin API

The Yorkie Admin API allows developers to interact programmatically with their Yorkie documents without using the Yorkie SDK. It is convenient 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

The Admin API accepts two credentials: a project's secret key with the API-Key scheme, and a login token with the Bearer scheme. Which ones a request may use depends on the endpoint:

  • Project-scoped endpoints work on a single project. These are GetProjectStats, the document endpoints (CreateDocument, ListDocuments, GetDocument, GetDocuments, SearchDocuments, UpdateDocument, RemoveDocumentByAdmin, CompactDocumentByAdmin, GetSnapshotMeta, ListChanges), the schema endpoints (CreateSchema, ListSchemas, GetSchema, GetSchemas, RemoveSchema), the channel endpoints (ListChannels, GetChannels, BroadcastByAdmin), and RevalidateAccess. Every endpoint documented on this page is project-scoped. They accept either credential:
    • The project's secret key, which carries the authority of a project admin and can call all of these endpoints. Keep it on your server and never ship it in client-side code.
    • A login token together with an x-yorkie-project header that names the project. The request is checked against your role in that project: endpoints that change the project (CreateDocument, UpdateDocument, RemoveDocumentByAdmin, CompactDocumentByAdmin, CreateSchema, RemoveSchema, BroadcastByAdmin, RevalidateAccess) need the admin or owner role, and the other, read-only endpoints are open to every member of the project.
  • User-scoped endpoints are every other authenticated endpoint, such as ListProjects, CreateProject, GetProject, UpdateProject, RotateProjectKeys, the member and invite endpoints, and the revision endpoints (ListRevisionsByAdmin, GetRevisionByAdmin, RestoreRevisionByAdmin). They act as a user account, and accept only a login token. GetProject and ListProjects return a project's secret key only to its admin and owner members; for the member role, secret_key is empty.

Wherever a login token is accepted and the request has no authorization header, the yorkie_session cookie, which the server sets when you sign in to the Dashboard, is used as the token instead.

LogIn, SignUp, ChangePassword and DeleteAccount take no authorization header: ChangePassword and DeleteAccount check the username and password in the request body instead. GetServerVersion needs a valid credential, and accepts either scheme.

A project-scoped endpoint can take the secret key with the API-Key scheme:

curl 'https://api.yorkie.dev/yorkie.v1.AdminService/ListDocuments' \
  -H 'content-type: application/json' \
  -H 'authorization: API-Key PROJECT_SECRET_KEY' \
  --data-raw '{"page_size": 10}'

A login token comes from LogIn. A user-scoped endpoint takes it alone:

curl 'https://api.yorkie.dev/yorkie.v1.AdminService/LogIn' \
  -H 'content-type: application/json' \
  --data-raw '{"username": "USERNAME", "password": "PASSWORD"}'
# {"token":"TOKEN"}


curl 'https://api.yorkie.dev/yorkie.v1.AdminService/ListProjects' \
  -H 'content-type: application/json' \
  -H 'authorization: Bearer TOKEN' \
  --data-raw '{}'

A project-scoped endpoint takes it with the project name:

curl 'https://api.yorkie.dev/yorkie.v1.AdminService/ListDocuments' \
  -H 'content-type: application/json' \
  -H 'authorization: Bearer TOKEN' \
  -H 'x-yorkie-project: PROJECT_NAME' \
  --data-raw '{"page_size": 10}'

These requests fail with permission_denied:

  • A credential the endpoint does not accept, such as a secret key on ListProjects, or a token without the x-yorkie-project header on ListDocuments.
  • A token whose user's role in the named project is too low for the endpoint, or whose user is not a member of it. A project that does not exist answers the same way, so the header cannot be used to find out which project names exist.

A request with no credential, an empty or blank secret key, or a key or token the server does not recognize fails with unauthenticated.

Documents Management

POST /yorkie.v1.AdminService/CreateDocument

This endpoint creates a new document in the specified project. If initial_root is provided, it is used as the initial content of the document. Otherwise, an empty document is created.

Request

Parameters:

  • 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: API-Key PROJECT_SECRET_KEY' \
  --data-raw '{
    "document_key": "document-1",
    "initial_root": "{\"type\":\"doc\",\"content\":[]}"
  }'
Response
{
  "document": {
    "id": "doc_abcdef",
    "key": "document-1",
    "project_name": "my-project",
    "root": "{\"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:

  • 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: API-Key PROJECT_SECRET_KEY' \
  --data-raw '{
    "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",
    "root": "{\"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. A pagination mechanism allows you to retrieve documents in batches. Provide the previous_id of the last document in the previous page to get the next page of documents.

To include the root of each document in the response, set the include_root parameter to true.

Request

Parameters:

  • 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_root: Whether to include root in the response.
curl 'https://api.yorkie.dev/yorkie.v1.AdminService/ListDocuments' \
  -H 'content-type: application/json' \
  -H 'authorization: API-Key PROJECT_SECRET_KEY' \
  --data-raw '{
    "previous_id": "doc_last_id",
    "page_size": 20,
    "is_forward": true,
    "include_root": 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",
      "root": "..."
    },
    {
      "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",
      "root": "..."
    }
  ]
}

POST /yorkie.v1.AdminService/GetDocument

This endpoint returns a document by its key.

Request

Parameters:

  • document_key: The key of the document.
curl 'https://api.yorkie.dev/yorkie.v1.AdminService/GetDocument' \
  -H 'content-type: application/json' \
  -H 'authorization: API-Key PROJECT_SECRET_KEY' \
  --data-raw '{
    "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:

  • document_keys: An array of document keys.
  • include_root: Whether to include root in the response.
  • include_presences: Whether to include presences in the response.
curl 'https://api.yorkie.dev/yorkie.v1.AdminService/GetDocuments' \
  -H 'content-type: application/json' \
  -H 'authorization: API-Key PROJECT_SECRET_KEY' \
  --data-raw '{
    "document_keys": ["document-1", "document-2"],
    "include_root": false,
    "include_presences": 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",
      "root": "...",
      "presences": "..."
    },
    {
      "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",
      "root": "...",
      "presences": "..."
    }
  ]
}

POST /yorkie.v1.AdminService/RemoveDocumentByAdmin

Remove a document.

Request

Parameters:

  • document_key: The key of the document.
  • force: Whether to force remove the document even if it is attached to clients.
curl 'https://api.yorkie.dev/yorkie.v1.AdminService/RemoveDocumentByAdmin' \
  -H 'content-type: application/json' \
  -H 'authorization: API-Key PROJECT_SECRET_KEY' \
  --data-raw '{
    "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:

  • 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: API-Key PROJECT_SECRET_KEY' \
  --data-raw '{
    "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:

  • 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: API-Key PROJECT_SECRET_KEY' \
  --data-raw '{
    "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"
    }
  ]
}

Channel Management

POST /yorkie.v1.AdminService/GetChannels

This endpoint retrieves channel information without requiring an SDK client to attach to the channels. It returns the session count (the number of connected clients) for the specified channels.

Channels support hierarchical keys using periods (.) as separators. When include_sub_path is enabled, the session count includes all clients connected to sub-level channels.

Request

Parameters:

  • channel_keys: An array of channel keys to retrieve information for.
  • include_sub_path: Whether to include session counts from sub-level channels in the total count.
curl 'https://api.yorkie.dev/yorkie.v1.AdminService/GetChannels' \
  -H 'content-type: application/json' \
  -H 'authorization: API-Key PROJECT_SECRET_KEY' \
  --data-raw '{
    "channel_keys": ["room-1", "room-1.section-1"],
    "include_sub_path": false
  }'
Response

If room-1 has 10 direct connections and room-1.section-1 has 20 connections, the response would be:

Case 1: Get exact channel session counts (include_sub_path: false)

When include_sub_path is false, the sessionCount for a channel includes only the direct connections to that channel. In this case, the session count for room-1 would be 10 and the session count for room-1.section-1 would be 20.

{
  "channels": [
    {
      "key": "room-1",
      "sessionCount": 10
    },
    {
      "key": "room-1.section-1",
      "sessionCount": 20
    }
  ]
}

Case 2: Get channel session counts including sub-levels (include_sub_path: true)

When include_sub_path is true, the sessionCount for a channel includes all clients connected to that channel and any sub-level channels. In this case, the total session count for room-1 would include both 10 and 20, totaling 30.

{
  "channels": [
    {
      "key": "room-1",
      "sessionCount": 30
    },
    {
      "key": "room-1.section-1",
      "sessionCount": 20
    }
  ]
}

Access Management

POST /yorkie.v1.AdminService/RevalidateAccess

This endpoint asks Yorkie to verify again the authorization of the project's open Watch streams after a permission changes in your system. On every Yorkie server, it drops the project's cached Auth Webhook decisions about the given keys, then asks the webhook again for each open Watch stream that watches any of them. A stream the webhook now denies is closed; streams it still allows keep running. See Applying Permission Changes.

Request

Parameters:

  • keys: The document or channel keys whose access changed, up to 1000. Keys match exactly: a channel key does not cover its sub-level channels. When empty, every open stream of the project is re-checked and all of its cached decisions are dropped.
curl 'https://api.yorkie.dev/yorkie.v1.AdminService/RevalidateAccess' \
  -H 'content-type: application/json' \
  -H 'authorization: API-Key PROJECT_SECRET_KEY' \
  --data-raw '{
    "keys": ["document-1", "room-1"]
  }'
Response

closedStreams is the number of streams closed across all servers.

{
  "closedStreams": 2
}

If the webhook could not be reached for some streams, those streams are left open and the request fails with codes.Unavailable (ErrRevalidationIncomplete). Retry the whole request.