General

Test Environment Guide

The test environment is an isolated copy of your workspace for development and integration testing. Runs made with a test API key never touch production data and never fire production webhooks, so you can exercise your whole integration, including webhook handlers, before pointing it at real documents.

How test mode works

Test mode is selected entirely by the API key. There is no separate base URL, header, or request flag.

Production keyTest key
Where requests goProduction environmentTest environment
Base URLSame (api.extend.ai, or your regional host)Same
Workflow and processor definitionsShared: the definition you edit in Studio is the one both environments runShared
Runs and their dataProduction onlyTest only; never visible from a production key
Webhook deliveriesProduction endpoints and subscriptionsTest endpoints and subscriptions only

Because definitions are shared, testing a workflow in test mode exercises exactly the definition that production will run. Because runs are isolated, nothing you submit in test mode appears in production run history.

A test key is still a real key that runs real models on the documents you send. It isolates data, not compute; use representative but non-sensitive sample documents.

Via the API

1

Create a test API key

In Studio, open the Developers tab, enable Test Environment, and create a key while test mode is on. Keys created in test mode are test keys; keys created with test mode off are production keys. Store the two separately, for example as EXTEND_API_KEY in your development environment and a different EXTEND_API_KEY value in production.

Developers tab in Studio with the Test Environment toggle enabled and a test API key listed

2

Configure the SDK with the test key

Every SDK reads EXTEND_API_KEY by default, so the simplest setup is to export the test key in your shell or .env and construct the client with no arguments. To choose the key explicitly, pass it to the constructor. Nothing else changes: the same code runs against production when given a production key.

import os
from extend_ai import Extend
# Reads EXTEND_API_KEY when token is omitted
client = Extend()
# Or select the key explicitly
client = Extend(token=os.environ["EXTEND_TEST_API_KEY"])
# Identical call in both environments; only the key decides where it runs
result = client.extract(
    file={"url": "https://extend-public-files.s3.us-east-2.amazonaws.com/freight-invoice.pdf"},
    extractor={"id": "ex_Xj8mK2pL9nR4vT7qY5wZ"},
)
3

Register test webhook endpoints

Webhook endpoints and subscriptions are per-environment. Create a second endpoint (for example a local tunnel URL) while test mode is on, or with the test key via the API, and subscribe your workflow to it. Test runs deliver only to test endpoints; production runs never reach them. The API calls are the same as in Configure webhooks with the API; the key you use decides which environment the endpoint belongs to.

Webhook endpoint configuration in Studio showing a test-mode endpoint

Workflow webhook subscription dialog with a test endpoint selected

4

Run and verify

Create runs with the test client exactly as you would in production. Use the same polling helpers or webhooks. When your handler behaves correctly end-to-end, switch the key and nothing else.

Via Extend Studio

Toggle Test Environment in the Developers tab to switch the dashboard into test mode. While it is on, workflows you run from Studio execute against test data, and the API keys and webhook endpoints you create belong to the test environment.

What you can do with test environments

ScenarioUse case
Local developmentEach developer uses their own test API key and webhook endpoints to avoid conflicts
Integration testingValidate webhook flows and event handling without impacting production systems
Workflow validationTest workflow logic with sample data before production deployment
Partner collaborationShare test access with external partners without exposing production data

Reference