# Make your first REST request

> Identify a workspace, search one page, and retry with the implemented REST API.

This tutorial uses an authorized workspace API key at `https://app.vencavo.com`. [Create an account](https://app.vencavo.com/auth/sign-up), verify your email, and select a workspace before creating a key. A successful nonempty search spends one credit.

## Prepare a temporary key

1. Sign in and select your workspace.
2. As an owner or admin, open **Developer access** and create a temporary key with `directory:read` and `billing:read`. Workspace identification is included.
3. Set `VENACOVA_ORIGIN` to `https://app.vencavo.com`. Set `VENACOVA_API_KEY` securely outside shell history and source control.

Do not substitute the marketing domain. Send exactly one credential type. Do not send browser cookies with the key.

## Identify the workspace

```sh
curl --fail-with-body --silent --show-error \
	-H "X-Api-Key: $VENACOVA_API_KEY" \
	"$VENACOVA_ORIGIN/api/v1/workspace"
```

Check the returned workspace ID, name, and data-connection status. Stop if the workspace differs from your intended workspace.

## Search one bounded page

Agree to spend at most one search credit. The following body searches companies in India using the supported structured country filter.

```sh
VENACOVA_OPERATION_KEY=$(uuidgen)
curl --fail-with-body --silent --show-error --include \
	-H "X-Api-Key: $VENACOVA_API_KEY" \
	-H 'Content-Type: application/json' \
	-H "Idempotency-Key: $VENACOVA_OPERATION_KEY" \
	--data '{"query":"","limit":10,"filters":[{"field":"companyCountry","include":["IN"],"exclude":[]}]}' \
	"$VENACOVA_ORIGIN/api/v1/directory/companies/search"
```

A nonempty page costs one credit. An empty page costs zero. Preserve the returned IDs, `source.mode`, `source.release`, `nextCursor`, and usage receipt. No particular company or result count is promised. Fixture results remain samples.

## Repeat the exact request

Run the same `curl` command again with the same operation key, credential, and body. A replay returns the recorded response body and `X-Idempotent-Replay: true`, without a second debit. The balance in that recorded body is historical.

To inspect the current balance, call `/api/v1/billing` with the same API key. Free requests and retries still count against [request limits](/developers/errors/).

## Inspect a returned company

Set `VENACOVA_COMPANY_ID` to an ID from your actual search result. URL-encode the ID when constructing the path. Do not use a fictional website domain or a fixture ID from another provider.

```sh
curl --fail-with-body --silent --show-error \
	-H "X-Api-Key: $VENACOVA_API_KEY" \
	"$VENACOVA_ORIGIN/api/v1/directory/companies/$VENACOVA_COMPANY_ID"
```

The free profile contains the available company fields and at most 50 previewed people. Preserve unknowns and source labels. Use the deployment's `/api/docs/reference` and `/api/openapi.json` for complete response and save schemas.

## Finish the test

Revoke the temporary key in **Developer access**. Repeat the workspace request and confirm rejection. Remove the secret from your shell.

```sh
unset VENACOVA_API_KEY
```

For a new page, pass the returned `nextCursor` as `cursor`, retain criteria, order, and limit, and generate a new operation key. An uncertain response requires the original key. Read [search credits](/developers/search/) and [error recovery](/developers/errors/) before continuing.

People searches also accept `{ "field": "companyId", "include": ["<company-id>"], "exclude": [] }` in `filters`, with up to 50 exact IDs. Keep the legacy top-level `companyId` empty and combine the selection with supported people filters. See [search criteria](/developers/search/) for selection, pagination and index-availability rules.