A GraphQL request in Tetiva is built around the schema: the app introspects the endpoint, then completes fields, generates an example operation and underlines invalid selections right in the editor. What goes over the wire is an ordinary POST with a JSON body of query, variables and operationName, so everything you know about headers and auth in HTTP applies here too.
Loading the schema#
Enter the endpoint (https://api.example.com/graphql) and press Load Schema. Tetiva runs an introspection query and splits the result into queries, mutations and types. The refresh button re-reads the schema after a deploy; an introspection failure is shown as a line next to the button.
Two things are worth knowing. First, only enabled rows of the Headers tab are sent with the introspection query — if the schema sits behind a token, put Authorization there; the Auth tab is applied when the request itself is sent, not when the schema is fetched. Second, introspection reads the Query and Mutation roots, so subscriptions never show up in the operation list.
The operation picker#
The picker to the left of the buttons lists every operation in the schema, grouped into Queries and Mutations, with search by name. Selecting one does three things at once: it stores the operation name, generates an example body, and fills in the variables.
The example is generated from the schema up to three levels deep. Operation arguments become variable declarations ($id: ID!) and are passed into the call, scalar and enum fields are written out, nested objects are expanded until the depth limit, and at the last level only scalars remain. Union and interface types get ... on Type branches. Variable values are type-based placeholders — replace them with real ones before sending.
The selected operation name is saved with the request and sent as operationName, which matters when the document holds several named operations.
Query and variables editor#
The editor is split vertically: the query on top, a collapsible Variables pane with JSON below. Both halves are stored with the request.
Once a schema is loaded, the query pane completes fields, types and arguments, and a linter underlines selections the schema does not accept — both features read the same schema the operation picker uses. Without a schema the pane is a plain text editor with syntax highlighting.
Cmd/Ctrl+Click on a type or a field opens it in the Schema tab. While the key is held, tokens are underlined so you can see what is clickable.
Environment variables are resolved in both the query text and the variables JSON: {{tenant_id}} is substituted before the call exactly as it is in a URL. See environments and variables.
The schema browser#
The Schema tab has two modes. Browse is an interactive walk: the operation list, the details of the selected one with its arguments and return type, and navigation from a field to its type. SDL is the same schema as text, with search across definitions. The search box filters both the operation list and the fields of the current type.
Open in Window moves the schema into a separate window, which helps when the query is long and switching tabs every minute gets old.
Sending and reading the response#
Cmd/Ctrl+Enter sends the request, Cmd/Ctrl+S saves it. The body is assembled as JSON with query, variables and operationName; Content-Type: application/json is set automatically, then enabled headers and the result of the Auth tab are added — see authentication.
The response is split into Data, Errors, Headers and Tests. That split matters: a GraphQL server usually answers HTTP 200 even when a resolver fails, so the status code alone is not enough — when the payload carries an errors array, the Errors tab lights up an indicator. The Tests tab is filled by scripts, and searching inside the payload is covered in response viewer.