How-to guides

How to create a Knowledge API token

Create, copy, and delete the tokens that let your own tools pull cited context from your GPTree documents and conversations, and choose whether a token can also spend credits on generated answers.

Knowledge API tokens let an outside tool read cited passages from your own documents and conversations. This guide covers creating one, using it, and turning it off.

Create a token

  1. Open Account from the user menu.
  2. Find the Knowledge API tokens panel on the Developer tab.
  3. Give the token a name that says where it will be used, for example "research script" or "internal dashboard".
  4. Select Create token.
  5. Copy the token immediately. It is shown once and cannot be retrieved later.

If you lose a token, delete it and create a new one. There is no way to reveal an existing token again, by design.

Use it

Send the token as a bearer token on your request:

Authorization: Bearer YOUR_TOKEN

Then call the search endpoint for ranked passages, or the context endpoint for a ready-to-use block of cited evidence. The full reference, with every endpoint and response field, is at the Knowledge API documentation.

Choose what the token can do

Tokens come in three flavours, and the first difference is money:

  • Read lets a tool search your knowledge and pull cited passages. It cannot spend credits.
  • Ask additionally lets a tool have GPTree write a cited answer. Generation is billed, so this one spends credits.
  • Ingest lets a tool add documents to your knowledge base and check on them. It cannot spend credits, but it can write. Sending text you have already extracted works on every plan; uploading a file for GPTree to read needs a Pro or Team plan.

Take read-only unless you actually need generated answers. A read token that leaks costs you nothing; an ask token that leaks can run up a bill; an ingest token that leaks can write into your knowledge base.

None of them can send messages, change settings, or read anything else in your account. That is why a token is safe to put in a script or a server environment variable in a way you would never do with your login.

Choose how long it lasts

You pick the lifetime when you create the token: 7, 30, 90 or 365 days, or no expiry at all. Ninety days is the default.

A token with no expiry keeps working until you delete it. That is a real option rather than a fallback, so choose it deliberately: a credential with no end date is one you have to remember to retire yourself. The expiry, or the absence of one, is shown next to every token in the list.

Tokens see material you own. Passages shared with you through project collaboration can be opened directly by their identifier, but do not appear in your search results yet.

Delete a token

  1. Open Account, Developer tab, Knowledge API tokens.
  2. Select Delete next to the token.
  3. Confirm.

Any tool using it stops working immediately. Delete a token the moment it is no longer in use, or if it may have been exposed.

Limits

  • Ten active tokens per account.
  • Optional expiry up to a year; expired tokens stop working and no longer count toward the limit.
  • Requests are rate limited per account.

Related reading