Umibudo API Manual
The Umibudo API lets external apps and tools connect with an API key. This manual explains how to get an API key, check it with the sayHello endpoint, and read your notes through the API.
Getting an API key
- Log in to Umibudo and open "Manage API Keys" in the settings details
- Enter a name and an expiration, then press "Create API Key"
- The issued key (a string starting with
umi_) is shown only on the screen right after creation. Copy it before closing and store it somewhere safe - Each user can have up to 10 keys. Delete keys you no longer need from the list (a deleted key stops working immediately)
Using your API key
Send the key in the Authorization header as Bearer <key> when calling the API. Do not put the key in the URL or the request body.
sayHello (connectivity check)
This endpoint checks that your API key works.
- Method:
GET - URL:
user_api/say_hello.php - Authentication:
Authorization: Bearerheader
Example (curl):
curl -H "Authorization: Bearer umi_1_xxxxxxxx" https://outline.uta.pw/user_api/say_hello.php
On success it returns JSON like this:
{"ok": true, "message": "Hello, (your display name)!", "user_id": 1, "display_name": "(your display name)"}
Listing your notes
Returns a list of your notes (read-only).
- Method:
GET - URL:
user_api/outlines.php - Authentication:
Authorization: Bearerheader - Response:
{"ok": true, "outlines": [{"id": 1, "name": "Note name", "visibility": "private", "published": false, "created_at": "...", "updated_at": "...", "edited_at": "..."}]}
Getting a note's contents
Returns a note's details and its items (read-only). Pass the id from the list as file_id.
- Method:
GET - URL:
user_api/outline_tree.php?file_id=<id> - Authentication:
Authorization: Bearerheader - Response:
{"ok": true, "file": {"id": 1, "name": "Note name", "...": "..."}, "nodes": [{"id": 1, "parent_id": null, "position": 0, "text": "Item text", "...": "..."}]} - A missing
file_id, or one that is not a positive integer, returns 400; a note that does not exist, or belongs to someone else, returns 404
Creating a note
Creates a new note. You can use the returned file_id right away to write items.
- Method:
POST - URL:
user_api/outline_create.php - Authentication:
Authorization: Bearerheader - Request:
{"name": "Note name"}(JSON body;nameis required, up to 120 bytes) - Response:
{"ok": true, "file_id": 1, "file": {"id": 1, "name": "Note name", "visibility": "private", "published": false, "created_at": "...", "updated_at": "...", "edited_at": "...", "encryption_version": 0}} - To create an encrypted note, add
"encryption_version": 1(omit it for an unencrypted note). If you have not set an encryption password yet, it returns 409 - The note currently open on screen does not change
Writing to a note
You can also create, update, and delete items in a note with an API key. Writes use POST with a JSON body (file_id is required).
- Create: send
{"file_id": 1, "parent_id": null, "position": 0, "text": "New item"}toPOST user_api/node_create.php - Update: send
{"file_id": 1, "id": 2, "text": "Edited item"}toPOST user_api/node_update.php(idis the item ID) - Delete: send
{"file_id": 1, "id": 2}toPOST user_api/node_delete.php
Example (curl):
curl -X POST -H "Authorization: Bearer umi_1_xxxxxxxx" -H "Content-Type: application/json" -d "{\"file_id\": 1, \"parent_id\": null, \"position\": 0, \"text\": \"New item\"}" https://outline.uta.pw/user_api/node_create.php
An API key acts with the full permissions of the user who created it, so a leaked key could be used to modify your notes. Do not create keys you do not need for writing, and delete any key that may have leaked right away.
Errors
- 400:
file_idis missing or is not a positive integer - 401 Invalid API key: the key is missing, incorrect, expired, or deleted. The response does not say which
- 404 File not found: the note does not exist, or belongs to someone else. The response does not say which
- 405 Method not allowed: the endpoint was called with a method other than
GET
Notes
- An API key acts with the same permissions as the user who created it. Do not share your key with others
- If a key may have leaked, delete it in API Key Management and create a new one
- A key with an expiration stops working automatically once it expires