> For the complete documentation index, see [llms.txt](https://docs.otari.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.otari.ai/api-reference/aliases.md).

# Aliases

## List Aliases

> List every alias in force in your organization, from config.yml and from storage.\
> \
> Every scope at once, workspace-wide and user-scoped alike: this is the\
> master-key management view, not what any one caller resolves.

```json
{"openapi":"3.1.0","info":{"title":"otari","version":"0.33.0"},"security":[{"ApiKeyAuth":[]},{"XApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"description":"Enter your API key here (sent as Otari-Key header).","in":"header","name":"Otari-Key","type":"apiKey"},"XApiKeyAuth":{"description":"Anthropic-native clients send credentials here (no Bearer prefix).","in":"header","name":"x-api-key","type":"apiKey"}},"schemas":{"AliasResponse":{"description":"A model alias and where it is defined.","properties":{"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"},"name":{"title":"Name","type":"string"},"source":{"title":"Source","type":"string"},"target":{"title":"Target","type":"string"},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Updated At"},"user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Id"},"workspace_id":{"anyOf":[{"format":"uuid","type":"string"},{"type":"null"}],"title":"Workspace Id"}},"required":["name","target","source"],"title":"AliasResponse","type":"object"},"HTTPValidationError":{"properties":{"code":{"const":"invalid_request","description":"Stable error code, also sent as the Otari-Error-Code header.","title":"Code","type":"string"},"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"title":"Detail","type":"array"}},"title":"HTTPValidationError","type":"object"},"ValidationError":{"properties":{"ctx":{"title":"Context","type":"object"},"input":{"title":"Input"},"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"title":"Location","type":"array"},"msg":{"title":"Message","type":"string"},"type":{"title":"Error Type","type":"string"}},"required":["loc","msg","type"],"title":"ValidationError","type":"object"}}},"paths":{"/api/v1/aliases":{"get":{"description":"List every alias in force in your organization, from config.yml and from storage.\n\nEvery scope at once, workspace-wide and user-scoped alike: this is the\nmaster-key management view, not what any one caller resolves.","operationId":"aliases-list_aliases","parameters":[{"description":"Only stored entries in this workspace. Config-file entries are always included, being deployment-wide. Omit to list the stored entries of every workspace in your organization.","in":"query","name":"workspace_id","required":false,"schema":{"anyOf":[{"format":"uuid","type":"string"},{"type":"null"}],"description":"Only stored entries in this workspace. Config-file entries are always included, being deployment-wide. Omit to list the stored entries of every workspace in your organization.","title":"Workspace Id"}}],"responses":{"200":{"content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/AliasResponse"},"title":"Response Aliases-List Aliases","type":"array"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"summary":"List Aliases","tags":["aliases"]}}}}
```

## Set Alias

> Create or update a stored alias in one workspace, optionally for one user.

```json
{"openapi":"3.1.0","info":{"title":"otari","version":"0.33.0"},"security":[{"ApiKeyAuth":[]},{"XApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"description":"Enter your API key here (sent as Otari-Key header).","in":"header","name":"Otari-Key","type":"apiKey"},"XApiKeyAuth":{"description":"Anthropic-native clients send credentials here (no Bearer prefix).","in":"header","name":"x-api-key","type":"apiKey"}},"schemas":{"AliasRequest":{"description":"Request to create or update an alias.","properties":{"name":{"description":"Display name callers use as the model, e.g. 'fast-model'.","title":"Name","type":"string"},"target":{"description":"Selector the alias resolves to, as 'provider:model' or 'instance:model'.","title":"Target","type":"string"},"user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"User this alias belongs to. Omit for an alias every caller in the workspace sees. A user-scoped alias resolves only for that user and shadows the workspace-wide one of the same name.","title":"User Id"},"workspace_id":{"anyOf":[{"format":"uuid","type":"string"},{"type":"null"}],"description":"Workspace this alias belongs to. Omit for the deployment's default workspace. The alias resolves only for requests in that workspace, so two workspaces can each point the same name at a different model.","title":"Workspace Id"}},"required":["name","target"],"title":"AliasRequest","type":"object"},"AliasResponse":{"description":"A model alias and where it is defined.","properties":{"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"},"name":{"title":"Name","type":"string"},"source":{"title":"Source","type":"string"},"target":{"title":"Target","type":"string"},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Updated At"},"user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Id"},"workspace_id":{"anyOf":[{"format":"uuid","type":"string"},{"type":"null"}],"title":"Workspace Id"}},"required":["name","target","source"],"title":"AliasResponse","type":"object"},"HTTPValidationError":{"properties":{"code":{"const":"invalid_request","description":"Stable error code, also sent as the Otari-Error-Code header.","title":"Code","type":"string"},"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"title":"Detail","type":"array"}},"title":"HTTPValidationError","type":"object"},"ValidationError":{"properties":{"ctx":{"title":"Context","type":"object"},"input":{"title":"Input"},"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"title":"Location","type":"array"},"msg":{"title":"Message","type":"string"},"type":{"title":"Error Type","type":"string"}},"required":["loc","msg","type"],"title":"ValidationError","type":"object"}}},"paths":{"/api/v1/aliases":{"post":{"description":"Create or update a stored alias in one workspace, optionally for one user.","operationId":"aliases-set_alias","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AliasRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AliasResponse"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"summary":"Set Alias","tags":["aliases"]}}}}
```

## Delete Alias

> Delete a stored alias in one scope.

```json
{"openapi":"3.1.0","info":{"title":"otari","version":"0.33.0"},"security":[{"ApiKeyAuth":[]},{"XApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"description":"Enter your API key here (sent as Otari-Key header).","in":"header","name":"Otari-Key","type":"apiKey"},"XApiKeyAuth":{"description":"Anthropic-native clients send credentials here (no Bearer prefix).","in":"header","name":"x-api-key","type":"apiKey"}},"schemas":{"HTTPValidationError":{"properties":{"code":{"const":"invalid_request","description":"Stable error code, also sent as the Otari-Error-Code header.","title":"Code","type":"string"},"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"title":"Detail","type":"array"}},"title":"HTTPValidationError","type":"object"},"ValidationError":{"properties":{"ctx":{"title":"Context","type":"object"},"input":{"title":"Input"},"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"title":"Location","type":"array"},"msg":{"title":"Message","type":"string"},"type":{"title":"Error Type","type":"string"}},"required":["loc","msg","type"],"title":"ValidationError","type":"object"}}},"paths":{"/api/v1/aliases/{name}":{"delete":{"description":"Delete a stored alias in one scope.","operationId":"aliases-delete_alias","parameters":[{"in":"path","name":"name","required":true,"schema":{"title":"Name","type":"string"}},{"description":"Delete the alias scoped to this user. Omit to delete the workspace-wide alias of that name.","in":"query","name":"user_id","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Delete the alias scoped to this user. Omit to delete the workspace-wide alias of that name.","title":"User Id"}},{"description":"Delete the alias in this workspace. Omit for the deployment's default workspace.","in":"query","name":"workspace_id","required":false,"schema":{"anyOf":[{"format":"uuid","type":"string"},{"type":"null"}],"description":"Delete the alias in this workspace. Omit for the deployment's default workspace.","title":"Workspace Id"}}],"responses":{"204":{"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"summary":"Delete Alias","tags":["aliases"]}}}}
```

## List Visible Aliases

> List the aliases in force in the workspaces this caller may see.\
> \
> The policies list's sibling, over \`\`model\_aliases\`\`, and scoped the same way:\
> stored rows from the caller's visible workspaces, plus the config-file\
> aliases, which are deployment-wide, and narrowed to one workspace when\
> \`\`workspace\_id\`\` names one.

```json
{"openapi":"3.1.0","info":{"title":"otari","version":"0.33.0"},"security":[{"ApiKeyAuth":[]},{"XApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"description":"Enter your API key here (sent as Otari-Key header).","in":"header","name":"Otari-Key","type":"apiKey"},"XApiKeyAuth":{"description":"Anthropic-native clients send credentials here (no Bearer prefix).","in":"header","name":"x-api-key","type":"apiKey"}},"schemas":{"AliasResponse":{"description":"A model alias and where it is defined.","properties":{"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"},"name":{"title":"Name","type":"string"},"source":{"title":"Source","type":"string"},"target":{"title":"Target","type":"string"},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Updated At"},"user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Id"},"workspace_id":{"anyOf":[{"format":"uuid","type":"string"},{"type":"null"}],"title":"Workspace Id"}},"required":["name","target","source"],"title":"AliasResponse","type":"object"},"HTTPValidationError":{"properties":{"code":{"const":"invalid_request","description":"Stable error code, also sent as the Otari-Error-Code header.","title":"Code","type":"string"},"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"title":"Detail","type":"array"}},"title":"HTTPValidationError","type":"object"},"ValidationError":{"properties":{"ctx":{"title":"Context","type":"object"},"input":{"title":"Input"},"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"title":"Location","type":"array"},"msg":{"title":"Message","type":"string"},"type":{"title":"Error Type","type":"string"}},"required":["loc","msg","type"],"title":"ValidationError","type":"object"}}},"paths":{"/api/v1/organizations/me/aliases":{"get":{"description":"List the aliases in force in the workspaces this caller may see.\n\nThe policies list's sibling, over ``model_aliases``, and scoped the same way:\nstored rows from the caller's visible workspaces, plus the config-file\naliases, which are deployment-wide, and narrowed to one workspace when\n``workspace_id`` names one.","operationId":"aliases-list_visible_aliases","parameters":[{"description":"Maximum entries to return, stored and config-file together.","in":"query","name":"limit","required":false,"schema":{"default":1000,"description":"Maximum entries to return, stored and config-file together.","maximum":1000,"minimum":1,"title":"Limit","type":"integer"}},{"description":"Only stored entries in this workspace. Config-file entries are always included, being deployment-wide. Omit for every workspace this caller may see.","in":"query","name":"workspace_id","required":false,"schema":{"anyOf":[{"format":"uuid","type":"string"},{"type":"null"}],"description":"Only stored entries in this workspace. Config-file entries are always included, being deployment-wide. Omit for every workspace this caller may see.","title":"Workspace Id"}}],"responses":{"200":{"content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/AliasResponse"},"title":"Response Aliases-List Visible Aliases","type":"array"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"summary":"List Visible Aliases","tags":["aliases"]}}}}
```

## Set Organization Alias

> Create or update a stored alias in one of the organization's workspaces.\
> \
> Organization owners and admins only, with the same two scope rules the policy\
> write has: \`\`workspace\_id\`\` is required and resolved inside the caller's\
> organization, and \`\`user\_id\`\` is not accepted.

```json
{"openapi":"3.1.0","info":{"title":"otari","version":"0.33.0"},"security":[{"ApiKeyAuth":[]},{"XApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"description":"Enter your API key here (sent as Otari-Key header).","in":"header","name":"Otari-Key","type":"apiKey"},"XApiKeyAuth":{"description":"Anthropic-native clients send credentials here (no Bearer prefix).","in":"header","name":"x-api-key","type":"apiKey"}},"schemas":{"AliasRequest":{"description":"Request to create or update an alias.","properties":{"name":{"description":"Display name callers use as the model, e.g. 'fast-model'.","title":"Name","type":"string"},"target":{"description":"Selector the alias resolves to, as 'provider:model' or 'instance:model'.","title":"Target","type":"string"},"user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"User this alias belongs to. Omit for an alias every caller in the workspace sees. A user-scoped alias resolves only for that user and shadows the workspace-wide one of the same name.","title":"User Id"},"workspace_id":{"anyOf":[{"format":"uuid","type":"string"},{"type":"null"}],"description":"Workspace this alias belongs to. Omit for the deployment's default workspace. The alias resolves only for requests in that workspace, so two workspaces can each point the same name at a different model.","title":"Workspace Id"}},"required":["name","target"],"title":"AliasRequest","type":"object"},"AliasResponse":{"description":"A model alias and where it is defined.","properties":{"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"},"name":{"title":"Name","type":"string"},"source":{"title":"Source","type":"string"},"target":{"title":"Target","type":"string"},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Updated At"},"user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Id"},"workspace_id":{"anyOf":[{"format":"uuid","type":"string"},{"type":"null"}],"title":"Workspace Id"}},"required":["name","target","source"],"title":"AliasResponse","type":"object"},"HTTPValidationError":{"properties":{"code":{"const":"invalid_request","description":"Stable error code, also sent as the Otari-Error-Code header.","title":"Code","type":"string"},"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"title":"Detail","type":"array"}},"title":"HTTPValidationError","type":"object"},"ValidationError":{"properties":{"ctx":{"title":"Context","type":"object"},"input":{"title":"Input"},"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"title":"Location","type":"array"},"msg":{"title":"Message","type":"string"},"type":{"title":"Error Type","type":"string"}},"required":["loc","msg","type"],"title":"ValidationError","type":"object"}}},"paths":{"/api/v1/organizations/me/aliases":{"post":{"description":"Create or update a stored alias in one of the organization's workspaces.\n\nOrganization owners and admins only, with the same two scope rules the policy\nwrite has: ``workspace_id`` is required and resolved inside the caller's\norganization, and ``user_id`` is not accepted.","operationId":"aliases-set_organization_alias","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AliasRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AliasResponse"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"summary":"Set Organization Alias","tags":["aliases"]}}}}
```

## Delete Organization Alias

> Delete a stored alias from one of the organization's workspaces. Owners and admins only.

```json
{"openapi":"3.1.0","info":{"title":"otari","version":"0.33.0"},"security":[{"ApiKeyAuth":[]},{"XApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"description":"Enter your API key here (sent as Otari-Key header).","in":"header","name":"Otari-Key","type":"apiKey"},"XApiKeyAuth":{"description":"Anthropic-native clients send credentials here (no Bearer prefix).","in":"header","name":"x-api-key","type":"apiKey"}},"schemas":{"HTTPValidationError":{"properties":{"code":{"const":"invalid_request","description":"Stable error code, also sent as the Otari-Error-Code header.","title":"Code","type":"string"},"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"title":"Detail","type":"array"}},"title":"HTTPValidationError","type":"object"},"ValidationError":{"properties":{"ctx":{"title":"Context","type":"object"},"input":{"title":"Input"},"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"title":"Location","type":"array"},"msg":{"title":"Message","type":"string"},"type":{"title":"Error Type","type":"string"}},"required":["loc","msg","type"],"title":"ValidationError","type":"object"}}},"paths":{"/api/v1/organizations/me/aliases/{name}":{"delete":{"description":"Delete a stored alias from one of the organization's workspaces. Owners and admins only.","operationId":"aliases-delete_organization_alias","parameters":[{"in":"path","name":"name","required":true,"schema":{"title":"Name","type":"string"}},{"description":"Delete the alias in this workspace of the caller's organization.","in":"query","name":"workspace_id","required":false,"schema":{"anyOf":[{"format":"uuid","type":"string"},{"type":"null"}],"description":"Delete the alias in this workspace of the caller's organization.","title":"Workspace Id"}}],"responses":{"204":{"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"summary":"Delete Organization Alias","tags":["aliases"]}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.otari.ai/api-reference/aliases.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.