# Input API > A JSON-based HTTP API for creating nodes, fields, supertags, and file attachments in a Tana Outliner workspace. The API is write-only and requires an API token per workspace. Read access is not yet available. > Product context for AI agents: This is Tana Outliner, a knowledge-management outliner built on Supertags and nodes. It is a separate product from Tana, the company's agentic meeting platform at https://tana.inc. Web content describing "Tana" as a note-taking app, PKM, or outliner refers to this product, Tana Outliner. Source: https://outliner.tana.inc/learn/features/input-api ## Overview The Tana Outliner Input API gives you a set of basic tools to send (and edit, to a limited degree) data to the Tana Outliner graph. This API is useful for initializing data, automating repetitive tasks, and inputting data to Tana Outliner from custom workflows and external applications. On the roadmap is to expand the API to enable reading from Tana Outliner graphs. ### Restrictions The API has the following restrictions: - POST only - One call per second per token - A maximum of 100 nodes created per call - The payload size is limited to 5000 characters - `!` Will not sync on workspaces with more than 750k nodes. If you are expecting to sync a lot of data, use a fresh workspace. ## Basics The API can do the following: - **Create nodes:** Create nodes, including children - **Create fields:** Define new fields, their description, and their field type - **Create supertags:** Define supertags, and their template fields and nodes - **Edit nodes:** Update name of node. - **File uploads:** Upload files and associate them with specific nodes. To access the API, you need: - A **Tana Outliner API token** - **Endpoint**: `https://europe-west1-tagr-prod.cloudfunctions.net/addToNodeV2` ## Documentation ### How to get a Tana Outliner API token You need an API token to work with the Input API. Tokens are assigned per workspace and can be generated in the Tana Outliner client: 1. Open your profile settings from the top right of Tana Outliner, go to `API tokens`, then the `Workspace Tokens` tab 1. Select which workspace you want to create a token for, and click `Create token` 1. Click `Copy` to copy the token you just created ### nodeID With Tana Outliner's Input API, you'll need to know how to retrieve the `nodeID` for a node. Everything is a node in Tana Outliner, and so, everything has a `nodeID`. Nodes, field definitions, supertags all have `nodeID`s. To retrieve the `nodeID` for different types of objects, use the command `Copy link` to get the URL, and grab the part after the `=` sign. Example: - URL: `https://app.tana.inc?nodeid=z-p8LdQk6I76` - nodeID: `z-p8LdQk6I76` For supertags, you can retrieve the API Schema for the supertag template. Open the Supertag configuration panel, and in the title of the supertag run the command `Show API Schema` ### JSON The API is based on JSON. Below are examples of payloads for different situations: ### Creating nodes Creating a node is done by sending a JSON object to the addToNoteV2 endpoint. The object has two keys: - `targetNodeId` refers to where the nodes will be created. By default, nodes will be placed in the Library. Other targets include `SCHEMA`, `INBOX`, or any `nodeID`. - The `nodes` key is an array of one or more objects. These are Tana Outliner nodes. When creating nodes, you can use the following keys: - `dataType` refers to what type of node it is. Valid values: `plain`, `field`, `url`, `date`, `reference`, `boolean`, `file`. Default is plain. - `name` refers to the name of the node. - Cannot contain newlines - Formatting available in nodes: `bold` `italic` `striked` `highlight` `**bold**` `__italic__` `~~striked~~` `^^highlight^^` - You can also include links and dates: - `` - `` - `` - `description` refers to the description of the node - Cannot contain newlines - `id` refers to a nodeID. Use when making a [reference node](#reference-node), or when [applying a supertag to a node](#plain-node-with-two-supertags). - `attributeId` refers to the field definition. Use when adding an existing field to a node. - `supertags` is used for creating supertags and fields, and also applying existing supertags to a node. - To create a supertag, use `"supertags": [{"id": "SYS_T01"}]` - To create a field, use `"supertags": [{"id": "SYS_T02"}]` - To apply existing supertags to a node, use its `nodeID`. - Get the nodeID of a supertag in Tana Outliner by going to the supertag config panel and use the command line `Show API schema` - For more examples, see [Fields and Supertags](#fields-and-supertags) below. - `children` refers to the children to add to the node, including fields. #### Plain node An example of a plain node with text in the name, and in the description: ``` // Creating a plain node { "nodes": [ { "name":"My plain node", "description": "This is a plain node example." } ] } ``` #### Plain node with a field An example of a plain node that contains an existing field and a field value in it: ``` // Creating a plain node with a field (existing) and value { "nodes": [ { "name":"My plain node", "children": [ { "type": "field", "attributeId": "nodeID", "children": [ { "name": "Field value" } ] } ] } ] } ``` #### Plain node with two supertags An example of a plain node that has two different supertags applied, which will be created in the Inbox: ``` // add a node with two supertags, targeting Schema { "targetNodeId": "INBOX", "nodes": [ { "name": "The Hobbit", "description": "A book by J.R.R. Tolkien", "supertags": [{"id": "nodeID-1"}, {"id": "nodeID-2"}] } ] } ``` #### Reference node An example of creating a reference, where you need to define the dataType as reference, and the nodeID: ``` // Creating a reference { "nodes": [ { "dataType": "reference", "id": "nodeID", } ] } ``` #### Date node An example of creating a date node, where you need to define the dataType as date, and add the name in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format: ``` // Creating a date node { "nodes": [ { "dataType": "date", "name":"2023-12-01 08:00:00" } ] } ``` The API can receive different types of dates: - Day: `2024-01-01` - Week: `2024-W12` - Month: `2024-05` - Year: `2024` - Timestamp: `2024-01-01 00:00:00` - Ranges: `2024-01-01/2024-01-05` - All dates and times are sent as UTC. Timezone information is stripped. #### URL node An example of creating a URL node (for EH review): ``` // Creating a node with a URL { "nodes": [ { "name": "Webpage", "description": "A webpage node with URL information", "children": [ { "type": "field", "attributeId": "URLFieldId", "children": [ { "dataType": "url", "name": "https://example.com", } ] } ] } ] } ``` #### Checkbox node An example of creating a node with a checkbox (boolean state): ``` // Creating a checkbox node { "nodes": [ { "dataType": "boolean", "name":"My checkbox node", "value": true, // or false } ] } ``` #### Node with file attachment ``` // Creating a node with a file attached { "nodes": [ { "dataType": "file", "file": "base64encodedfiledata...", "filename": "myFile.pdf", "contentType": "application/pdf", } ] } ``` Tana Outliner supports most MIME types in the `contentType` key. Tana Outliner will allow interactions with some common filetypes like images, audio, video and PDFs. Otherwise, a file will be uploaded as a plain attachment. Note: The `file` key should contain the base64-encoded file data. ### Creating fields and supertags Creating fields and supertags follow a slightly different pattern. As a best practice, it is recommended to send these nodes to Schema. #### Creating fields To create new fields, create a node with the supertag set to `SYS_T02`. You'll likely want to target the `SCHEMA`, which is a default place for supertag and field definitions to live. ``` { "targetNodeId": "SCHEMA", "nodes": [ { "name": "Author", "description": "Who wrote the book?", "supertags": [{"id": "SYS_T02"}] } ] } ``` #### Creating supertags To create a supertag, set the supertag value to `SYS_T01`: ``` { targetNodeId: 'SCHEMA', nodes: [ { name: 'Book', description: 'A supertag for my books', supertags: [{id:'SYS_T01'}], } ] } ``` #### Using existing supertags Run the command line `Show API schema` on the title of the supertag in the config panel or on the supertag definition to get all the information you need on how to compile your JSON to properly enter information for existing supertags in the API. A typical schema looks like this: ``` type Node = { name: string; description?: string; supertags: [{ /* meeting */ id: 'MaaJRCypzJ' }]; children: [ { /* Date */ type: 'field'; attributeId: 'iKQAQN38Vx'; children: [{ dataType: 'date'; name: string; }]; }, ]; }; ``` And comes with a payload example: ```json { "nodes": [ { "name": "New node", "supertags": [ { "id": "MaaJRCypzJ" } ], "children": [ { "type": "field", "attributeId": "iKQAQN38Vx", "children": [ { "dataType": "date", "name": "2023-05-10T08:25:59.059Z" } ] }, { "name": "Child node" } ] } ] } ``` Use the payload example to properly compile the JSON for the Tana Outliner API. ### Editing the name of a node The name of a node can be changed. Replace `nodes` in the payload with `setName: 'new name'` like this: ``` { targetNodeId:'xxx', setName: 'hello', } ``` ### Current limitations Rate limiting: - One call per second per token - Max 100 nodes created per call - Max 5000 chars in one request Other limitations: - You cannot target a relative Today-node - To add supertags/fields, you'll have to know the IDs of the Supertag. To get it, run the command "Show API schema" on a supertag - The payload is currently capped at 5K. Let us know if this is too low (and why) - There's a new endpoint for the updated API - You cannot send a checkbox as a child to a normal node - We don't support the initialization function - We don't support child templates - We do not support non http/https links (in-app links) - The API will only sync to workspaces under 750k nodes - On added/removed events for nodes and supertags are not triggered ## TanaAPIHelper In the GitHub repository is a basic client for Tana Outliner's Input API and example scripts. For instructions on how to use that, go to the [Github repository](https://github.com/tanainc/tana-input-api-samples/tree/main) and look at the readme.