Tetiva
Sign in
All sections

Tetiva documentation

Tetiva is a desktop API client that speaks HTTP, gRPC, GraphQL and WebSocket in one window. Collections, environments, cookies and request history live in a SQLite file on your machine, an account is only needed for sync and publishing, and the app collects no telemetry. These docs describe what the client does today: installation, your first request, the four protocols, scripting and tests, import from Postman, Insomnia, Hoppscotch, OpenAPI and HAR, sync, publishing collections, and the built-in MCP server for AI agents.

Start here

  • Installation — DMG for macOS, installer for Windows, .deb for Ubuntu and Debian, system requirements.
  • Quick start — first request in two minutes.
  • Migrating from Postman — v2.1 export, what carries over, what you rewrite by hand.

How the client works

Data stays on disk. Everything goes into ~/.tetiva/data.db. Collections, environments and history work offline, with no sign-in and no server.

The network is only used when you ask. The client reaches out in eight cases: you send a request; you open a saved GraphQL or gRPC request that reads its schema from the server — introspection for GraphQL, reflection for gRPC, while a local schema or .proto file is read from disk; the update check is on, and with it the download of a new version (two switches in settings); sync is connected; you sign in through the browser; you fetch an OAuth 2.0 token on the Auth tab; you are signed in and publish a collection or look at its page's status on the Publish tab, in the Publications panel or in the collection menu, and while publishing is on, the app also fetches the publication list by itself at startup and when you switch workspaces; you import a published collection from its link or with Open in Tetiva, and the app downloads it from api.tetiva.app. No analytics, no usage reports.

Four protocols, one interface. Tabs, collections, environments and auth behave the same for HTTP, gRPC, GraphQL and WebSocket — only the request editor changes.

Scripts run in a sandbox. Pre-request and post-response scripts execute on the goja engine with no file system, no network access and a 5-second timeout. See Scripting.

Import and export. Collections come in from Postman v2.1, Insomnia, Hoppscotch, OpenAPI and Swagger specs and HAR files, environments from Postman and Hoppscotch files. They go out as Postman v2.1 JSON and Postman environment files, so you can leave whenever you want — see Import and export.

The desktop client is free and open source — download it here. The sections below list every page; each one answers a single question end to end.

Getting started

  • Installation

    Install Tetiva on macOS, Windows and Linux: DMG, installer, the .deb package, system requirements, the SmartScreen warning, and where data lives.

  • Quick start

    Send your first request in Tetiva in two minutes: create a collection and a request, set the URL, hit Cmd+Enter, read the response tabs.

Core features

  • Collections

    Workspaces and collections in Tetiva: nesting, the Markdown description editor with tables, collection-level auth, multi-select and moving items.

  • Environments and variables

    Tetiva environments, the {{var}} syntax, resolution order, inline highlighting and hover peek, secret variables, and variables written by scripts.

  • Authentication

    The nine entries of the Auth tab in Tetiva: Basic, Bearer, API Key, OAuth 2.0, JWT, Digest and AWS Signature, plus Inherit and the order of operations.

  • Request body

    The six body types in Tetiva — JSON, XML, Raw, Form Data, Binary, None — plus lossless type switching, file uploads, and Content-Type handling.

  • Scripting

    Pre-request and post-response scripts in Tetiva: supported pm.* calls, pm.expect, what a failing script does, sandbox limits, inheritance, tests and console.

  • Response viewer

    The response pane in Tetiva: Body, Headers, Cookies and Tests tabs, body search, comparing responses, binary payloads, examples and request history.

  • Import and export

    Import Postman, Insomnia and Hoppscotch collections, OpenAPI specs and HAR files, export to Postman v2.1, paste a cURL command, copy a request as code.

  • Keyboard shortcuts

    Every keyboard shortcut in Tetiva: sending and saving requests, tabs, editors, response search and comparison, and the collection tree.

Protocols

  • HTTP requests

    Methods, URL, query parameters, headers and cookies in Tetiva, pasting a cURL command into the URL bar, and the Docs tab that holds the description.

  • gRPC

    Unary gRPC calls in Tetiva: TLS via grpcs://, schema from server reflection or .proto files, method picker, example messages, metadata and the response.

  • GraphQL

    GraphQL in Tetiva: introspection or a schema file, an operation picker that generates examples, the query and variables editor, the schema browser.

  • WebSocket

    WebSocket in Tetiva: six request tabs, JSON, Text and Binary formats, saved messages, ping and subprotocols, the pre-connect script and the session log.

Sync & account

  • Sync and account

    Signing in to Tetiva Cloud through the browser, self-hosted servers, email confirmation, the device list, status icon states, and what leaves your machine.

  • Publishing a collection

    Turn a Tetiva collection into a read-only page on share.tetiva.app: visibility, preview and secret scrubbing, updates, counters and plan limits.

Advanced

  • MCP server

    Enable the MCP server built into Tetiva, pass its access token, connect Claude Code or Cursor, and use all 33 tools over collections, requests and sync.

  • Settings

    Tetiva settings: interface language and theme, editor font, publishing, the MCP server for AI agents, update checks, and where the database and logs live.

  • Troubleshooting

    SmartScreen and Gatekeeper warnings, starting Tetiva with logs, moving or resetting the data directory, the MCP token, browser sign-in, and reporting bugs.

Migration