Skip to main content

​
1. Create an API token

Create a token at the account scope that should own the integration, then store it outside source code and prompts. Vida API authentication uses the token query parameter. See Authentication for the scope-specific menu locations.

​
2. Identify the account scope

Most integrations need a stable Agent account ID:
  • targetAccountId selects the account whose resources the request should use.
  • accountId owns a newly created Task and normally matches targetAccountId.
  • agentConfigId identifies a staging, live, or saved Agent configuration; it is not an account ID.
  • Computer Agent routes place the selected account ID directly in /computer/accounts/{targetAccountId}.
Higher-level tokens can use targetAccountId for authorized child accounts. Never assume an organization account, Agent account, and Agent configuration share the same ID.

​
3. Identify the key, then read the target

First identify the account that owns the key. Do not include targetAccountId in this request:
Use the returned account type and hierarchy to understand the key’s scope as described in Authentication. Preserve any permittedAccountIds restriction. If the work concerns another authorized account, read that target separately:
The first response identifies the key owner; the second identifies the selected target. Keep them separate and confirm both before making changes. For Agent configuration, read staging first. For a Computer Agent, read its account status and health first.

​
4. Read, change, and verify

Use the same safe pattern for every resource:
  1. Read the current state and exact schema.
  2. Apply the smallest intended change.
  3. Re-read the resource.
  4. Verify the real capability, not only the write response.
An accepted lifecycle operation, Task, login flow, or scheduled run is not proof of completion.

​
5. Continue with a workflow guide

For complete examples that combine several resource families, use the API cookbooks: Using an AI agent to build or operate your integration? Install the Vida API Skill so it has the same scoping and verification rules.