Skip to content

For applications

People read Depositori in the browser. Software reads the same definitions in two ways. Both are on the Organisation page.

For Claude, ChatGPT or another AI agent that you use yourself.

  1. Open Organisation and find Connect an AI agent.
  2. Copy the address and add it in your agent as a connector. The steps for Claude, ChatGPT and Claude Code are under the address.
  3. The agent asks you to sign in to Depositori once. After that it works in your organisation as you, with your role.
Connect an AI agent: the address to give the agentConnect an AI agent: the address to give the agent

Nothing to paste besides the address, and no key to keep safe. You see and disconnect your agents under your name at the bottom left, Connected apps.

Everything you can do in the app, your agent can do too, as a tool, and nothing more. It gets the tools of your role: a reader’s agent reads, asks questions and suggests changes to KPIs; a contributor’s also edits the glossary, notes and descriptions; an owner’s also manages connections, imports and people; an admin’s also manages the workspace. Your role is checked again in the organisation each call names. A tool your role doesn’t have is not listed, and calling it anyway is refused before it runs.

  • As you. An agent connected this way acts in your name. What it changes is recorded as yours, for example in the history of a KPI or an open point. A KPI suggestion, an approval and every change to an open point are always made by a person, so only an agent signed in as you can make them, not an API key.
  • It asks first. What can’t be undone, such as deleting an import or a connection, removing a person or revoking an API key, needs an explicit confirmation in the tool. A well-behaved agent asks you before it confirms.
  • Live numbers. The number tools (query_kpi, query_metrics, list_values, run_dax) are there only when an Admin allowed queries for the organisation (Allow queries through the API under Edit organisation). run_dax runs a DAX query of the agent’s own on a model, so it can return detail rows, not only totals: at most 200, with personal and restricted columns left out and e-mail addresses masked. That is why it is only for a person signed in, never for an API key.

A few things are never done by an agent. For those, the agent gives you a link to the right form in the app, for you to open:

  • Secrets: creating an API key (its token), adding a database login, setting the AI key, and adding or changing a company sign-in (its client secret). A password, key or client secret never goes through an AI’s context.
  • Sign-ins: connecting a Microsoft account or another source account, which happens in your browser.
  • Uploads: files such as a Power BI template.
  • Confirming that another tool server’s tool only reads (It only reads): an agent doesn’t vouch for the tools it may then call itself.
  • Approved audiences: where an organisation’s app-account tokens may be sent, an Admin’s choice.
  • Taki’s chat: the agent is the AI itself, and gets Taki’s tools to read and compute.

Each role has the tools of the roles above it in the list, and more. A person’s only means that an API key never gets the tool. Choose a role to see its tools.

Reader (59 tools)
ToolDoesHints
approve_kpi_suggestionApprove a suggestion on a KPI you owndestructive, a person's only
call_toolRun a read-only tool of a connected MCP serverreads, open world
compare_modelA model's original source, its Ossie document and its translation to target side by side, per dataset, field, relationship and metricreads
confirm_open_pointConfirm that the source now matches the approved definition, after the model was read again: the point closesdestructive, a person's only
decline_open_pointClose an open point as won't do, with the reasondestructive, a person's only
describe_metricA metric of a modelreads
describe_tableA table of a modelreads
draft_open_point_queryHave the organisation's AI draft the proposed query of an open point (replacing the one there), marked as an AI draft that a person checksdestructive, open world, a person's only
findFind KPIs, metrics and tables by the organisation's own words, best first, each with why it matched (its name, a synonym, a concept, its definition)reads
fork_kpi_suggestionMake a suggestion on a KPI you own a new KPI of its own, named nameadds, a person's only
get_analyst_statusWhether Taki, the organisation's AI analyst, can answer and, for what is missing, who may fix itreads
get_conceptA business conceptreads
get_connection_metadataA warehouse connection's latest metadata snapshot (a summary, or with full every definition) and its historyreads
get_jobOne of your jobsreads
get_kpiA KPI in fullreads
get_kpi_governanceA KPI's owners (by display name), its open suggestions to change the definition with who approved and who is still to, the history of suggestions and decisions, and what uses it (models, Power BI reports, dbt models, agents)reads
get_modelA model as the site shows itreads
get_model_documentA model as a documentreads
get_model_versionsThe model's versions per object of its Ossie documentreads
get_ontologyThe ontology as its stored YAML text (null when there is none yet), with its version and last changereads
get_open_pointOne open point in full: the approved definition, the metric's query when raised and as last read, the proposed query, what uses the KPI, and the historyreads
get_organisationAn organisationreads
get_profileWhat KPIs inheritreads
get_sessionThe account you read the organisation's sources with, or nullreads
get_setupWhere the organisation stands, step by step, and the next stepreads
get_structureThe parts of the organisation KPIs are grouped byreads
list_accountsThe accounts you see in the organisation (your own and its app accounts)reads
list_conceptsEvery business conceptreads
list_connection_toolsAn MCP connection's tools as last read, each with whether it may be called, and whether you are signed in to it (search_tools and call_tool use them)reads
list_credentialsThe stored logins of the organisation you may seereads
list_importsThe organisation's imported models (each with its id, source and state) and your reads that are runningreads
list_jobsYour recent jobs in the organisation (imports, reads), newest firstreads
list_kpisEvery KPIreads
list_modelsThe organisation's semantic modelsreads
list_ontology_templatesThe sector templates an ontology can start fromreads
list_open_pointsOpen points for engineers: changes to a model's metric that an approved KPI definition asks for (or that someone raised by hand), on models you may seereads
list_organisationsThe organisations you have a role in, each with your role and whether it allows queriesreads
list_questionsThe organisation's open questions about its definitions (a KPI's unit, a metric's meaning), for contributors to answerreads
list_reportsWhat the reports built on an import's model use, as last readreads
list_source_kindsThe kinds of source a model can be imported from (Power BI, dbt, a database, ...)reads
list_sourcesThe data sources the organisation's models read, each with the connection it matches, and the connections to suggestreads
list_systemsThe business systems the data comes from (a till, an ordering platform), with the tables from eachreads
list_translate_targetsThe platforms a model can be translated to with Ossie's converters (translate_model, compare_model)reads
list_valuesThe exact values of a column (Table[Column]) to filter query_kpi on, optionally only those containing a textreads, where queries are allowed
list_waiting_suggestionsThe open suggestions on KPIs you own that wait for your approvalreads
mark_open_point_doneSay the change is made in the source; the point then waits for the model's next read and a confirmationadds, a person's only
metric_sqlOne SQL statement that computes a metric on the warehouse in a filter contextreads
query_kpiCompute a KPI the way the organisation defines itreads, where queries are allowed
query_metricsCompute metrics of a model by name (describe_table and find name them), for what query_kpi can't expressreads, where queries are allowed
raise_questionAsk the organisation a question about one of its definitions, for a contributor to answeradds
refresh_kpi_suggestionBring a stale suggestion (the KPI's approved text changed since it was made) up to datedestructive, a person's only
reject_kpi_suggestionReject a suggestion on a KPI you own, with the reasondestructive, a person's only
run_daxRun a DAX query (EVALUATE ...) on a modelreads, where queries are allowed, a person's only
search_toolsFind tools of the organisation's connected MCP servers (Jira, a database, its own tools) that can answer a question, by what they doreads, open world
set_open_point_proposalWrite or replace the proposed query of an open point (empty removes it); nothing is written to the sourcedestructive, a person's only
starter_questionsWhat to ask about a model firstreads
suggest_kpi_changeSuggest a change to a KPI's definition and/or calculation note, with the reasonadds, a person's only
translate_modelTranslate a model to another platform (list_translate_targets) with Ossie's convertersreads
withdraw_kpi_suggestionWithdraw a suggestion you made while it is opendestructive, a person's only
Contributor (21 tools)
ToolDoesHints
add_discovered_kpisMake these KPIs found across the models (their keys, from list_discovery) draft KPIs, linked in every model, with a question on which definition leads where they differadds
add_kpi_candidatesMake these KPI candidates (their ids, from list_kpi_candidates) draft KPIs, linked to their measures, with a question where a candidate has severaladds
answer_questionAnswer one of the organisation's questions (list_questions)destructive
apply_ontology_templateMerge a sector template (list_ontology_templates) into the ontologyadds
check_metricCheck a metric's SQL translation on the warehouse against Power BI, as a grand total or by group_by [table, column]adds
dismiss_kpi_candidatesLeave these KPI candidates out for gooddestructive, confirm
dismiss_questionTake a question off the list unanswereddestructive
draft_descriptionsHave Claude draft descriptions and synonyms of an import's tables and metrics from their names, columns and expressions (with the organisation's AI on)destructive, open world
draft_metricHave Claude draft a SQL translation of a DAX measure the translation rules can't translate (with the organisation's AI on)adds, open world
edit_ontology_itemAdd (item, no id), change (id and itemdestructive, confirm
explain_discovered_kpiWhat the definitions of one KPI found across the models count differently, in plain words, by Claude (with the organisation's AI on), from the definitions onlyreads, open world
list_discoveryThe organisation's KPIs found across all its models, each with the models it is in, and where their definitions differreads
list_kpi_candidatesAn import's KPI candidates, best firstreads
propose_linkPropose that a model object is a KPI or is about a concept, as a draft for the organisation to review (never a reviewed link)adds
raise_open_pointRaise an open point by hand for the engineer: on a KPI (a point per model that computes it) or on one metric, with a noteadds, a person's only
read_reportsRead again from Power BI what the reports built on a Power BI import's model use (list_reports gives the last read), as the organisation's account in useadds
reopen_questionPut an answered or dismissed question back on the listdestructive
replace_ontologyReplace the whole ontology with this YAML textdestructive, confirm
review_linkReview a link of a KPI or concept to a model objectdestructive, confirm
set_descriptionWrite, change or remove (empty or null) the description of a table, or of one of its columns, by handdestructive
set_import_noteSet one note on an import that its definition doesn't say, kept across re-importsdestructive
Owner (47 tools)
ToolDoesHints
add_connectionAdd a connection of type (powerbi, azure_sql, dbt, mcp, ...) with its type's fieldsadds
app_linkThe link to the app's own form for what no tool does, for the person to openreads
assign_open_pointGive an open point to another engineer, by member keydestructive, a person's only
copy_importCopy an import under a new name, without reading its source againadds
delete_connectionDelete a connection (models read through it stay)destructive, confirm
delete_credentialRemove a stored login of yours and its secretdestructive, confirm
delete_importDelete an import of yours, its model and what is kept with itdestructive, confirm
discover_connectionWhat a login can see for a connection being filled in (its servers, databases, workspaces), to pick its fields fromreads, open world
get_ai_keyWhose AI key the organisation uses (its own, the workspace's, none)reads
get_import_progressHow the read of an import goesreads
get_powerbi_catalogEvery workspace a Power BI connection's account can see, with its models and what is imported alreadyreads
import_allImport these Power BI models ([{workspace_id, workspace, dataset_id, dataset_name}] from get_powerbi_catalog), a job each (list_jobs)adds, open world
import_connectionRead a connection into a model named name (a database's tables, a Superset's datasets, a dbt project), only schemas if givenadds, open world
import_powerbi_modelRead a Power BI model (dataset_id and dataset_name, from list_connection_models or get_powerbi_catalog) through a connection, or a workspace_id and workspaceadds, open world
invite_memberInvite someone by e-mail as contributor or reader (someone who signed in before gets the role at once), or take an invite back with role nulldestructive, confirm
link_sourceSay a model's source at this location ({server, database, ...} as list_sources shows it, or {database}) reads through this connection, so lineage follows itadds
list_approved_audiencesThe token audience and host pairs an admin approved for the organisation's app accountsreads
list_connection_datasetsThe datasets an Amazon QuickSight connection's login can see, with their folders and kindreads
list_connection_modelsThe semantic models in a Power BI connection's workspace, with what is imported alreadyreads
list_connection_schemasThe schemas of a database connection, with how many tables and views each holdsreads
list_membersThe organisation's members (user id, role, e-mail and name as the app shows them to an owner), its waiting invites and its API keys (never a token)reads
list_powerbi_reportsThe Power BI reports the account in use can see, with the models they are built onreads
list_powerbi_workspacesThe Power BI workspaces the account in use can seereads
read_connection_metadataRead a warehouse connection's metadata again and rebuild the models' lineageadds
read_connection_toolsRead an MCP connection's tools again from its server (list_connection_tools gives the last read)adds, open world
refresh_importRead an import again the way it was madedestructive, open world
remove_accountRemove an account and its tokensdestructive, confirm
remove_ai_keyRemove the organisation's own AI keydestructive, confirm
revoke_api_keyRevoke an API key (its id, list_members)destructive, confirm
set_connection_analystLet Taki run read-only SQL on this database connection (on), or notdestructive
set_connection_per_userWhether each person signs in to this MCP connection's server themselves (on) or it reads with one shared logindestructive, confirm
set_connection_visibilityShare a connection of yours with the organisation (entity) or make it privatedestructive
set_import_scheduleRead an import again on a scheduledestructive
set_import_visibilityShare an import of yours (its id, list_imports) with the organisation (entity) or make it privatedestructive
set_kpi_ownersAssign a KPI's owners, by the member keys get_kpi_governance lists under membersdestructive, a person's only
set_memberGive a member (their user id, list_members) the role contributor or reader, or remove them with role nulldestructive, confirm
set_profileChange the organisation profile (locale, reporting_currency, vat, fiscal_year_start, week, time_zone, about, sites, groupings, steering)destructive, confirm
sign_out_accountSign an account out (list_accounts)destructive
sign_out_sessionSign out the account you read the organisation's sources withdestructive
test_connectionTest a connectionadds, open world
test_new_connectionTest a connection before adding it, with the same arguments as add_connectionreads, open world
unlink_sourceTake a link_source backdestructive
update_connectionChange a connection's name, fields and logindestructive
update_credentialRename a stored login of yours (list_credentials) or change who may use itdestructive
update_organisationChange the organisation's name, its description (empty removes it), AI on or off (on needs an AI key) and, as an admin only, whether it allows queriesdestructive
use_accountRead the organisation's sources with this signed-in account (list_accounts) from now ondestructive
download_my_dataEverything this workspace stores about the person the agent acts for, and nothing about anyone else; never for an API key (parity.PERSON_ONLY)reads
Admin (11 tools)
ToolDoesHints
create_organisationAdd an organisationadds
delete_organisationDelete an organisation (its id, always given) and everything stored for itdestructive, confirm
get_workspace_ai_keyWhose AI key organisations without their own use (the workspace's, none)reads
list_monitorsThe monitors that read the workspace's status (docs/monitoring.md): name, host, who allowed it, last usedreads
list_sign_insThe workspace's own sign-ins (identity providers)reads
list_workspace_peopleEveryone in the workspace with their organisations and roles there, whether they are admin and why, and the waiting invitesreads
remove_sign_inRemove one of the workspace's sign-ins (its id, list_sign_ins)destructive, confirm
remove_workspace_ai_keyRemove the workspace's AI keydestructive, confirm
revoke_monitorRevoke a monitor's token (its id, list_monitors)destructive, confirm
set_workspace_adminMake someone (their user id, list_workspace_people) admin of the workspace, or take it backdestructive, confirm
workspace_app_linkThe link to the app's Workspace settings for what no tool does, for the person to openreads

An owner can add another MCP server as a connection (Add connection, MCP server), such as Jira, Atlassian or Notion. Your agent then reaches its tools through Depositori’s own address. Depositori reads the server’s list of tools; only the tools an owner confirms as read-only (It only reads) can be called. A tool that changes data is never run.

  • The Server URL is the server’s address, such as https://mcp.example.com/mcp. On a hosted Depositori it must be a public https:// address; an http:// address, or one on an internal network, is refused.
  • The server reads with an API token, an OAuth sign-in, or nothing, as it needs.

Some tool servers read as each person. Then the Organisation page shows everyone, readers included, the section Your accounts for agent tools. Choose Connect account next to a server to connect your own account; your agent’s calls to that server then use it, and you see only what your own account allows. Connect again renews it.

For scripts, pipelines and applications that run without a person. You need the Owner role.

  1. Open Organisation and find API keys.
  2. Choose Create key, name it after the application that will use it, and choose Create.
  3. Copy the key now. You will not see it again.
Create an API key, named after the app that uses itCreate an API key, named after the app that uses it

A key reads one organisation, as a Reader, and never more: besides reading, the only thing it can do is raise a question about a definition, as a reader can. It never gets the tools that are a person’s only (the table above): run_dax, suggesting or deciding a KPI change, and working on an open point. Whoever holds a key isn’t a named person, and those need one. Revoke stops it at once.

By default a key reads definitions only. For an application to have KPIs computed, an Admin turns on Allow queries through the API under Edit organisation.

Your developers find every route of the API, with what it takes and what it answers, on the API documentation page: /api/v1/docs on your Depositori’s address, such as https://depositori.example/api/v1/docs. API keys on the Organisation page links to it.

The API documentation page: the routes of the Depositori API, with Authorize at the right
  1. Open the page. It needs no sign-in: it holds no data of any organisation.
  2. To try a route, choose Authorize, paste an API key (it starts with dpk_) and choose Authorize again. The page forgets the key when you close it.
  3. Open a route, choose Try it out, fill in what it asks (such as your organisation’s id), and choose Execute. The answer shows below it.

Without a key, a route answers as whoever is signed in to Depositori in that browser, with their role. The page loads nothing from other websites.

The same description, as a file for tools that read OpenAPI, is at /api/v1/openapi.json.