Netlify’s domain centers on Accounts, Sites, and Deploys. Accounts own Sites and DNS zones; Sites contain Builds, Deploys, Functions, Assets, Forms/submissions, Snippets, Split Tests, Dev Servers, and Service (addon) instances. Many operations require one of the canonical IDs — account_id or account_slug, site_id, deploy_id, build_id, or zone_id — and knowing where each ID appears is the fastest way to reach the right resource.

Key entities and how they relate

• Accounts: represent teams/owners. Responses include both account_id and account_slug in different places. Memberships, billing/payment methods, and account-scoped environment variables live at account level.
• Sites: belong to an Account. Most site-scoped operations (deploys, builds, assets, functions, forms, snippets, split tests, dev servers) require site_id.
• Deploys and Builds: Deploys are atomic site snapshots; Builds are Netlify build jobs that produce deploys. A deploy is addressed by deploy_id; a build by build_id.
• DNS Zones and Records: DNS zones are tracked separately (zone_id) and can be associated to sites via site DNS configuration operations. DNS records are nested under a zone and use dns_record_id.
• Environment variables: keyed by key and scoped to an account_id and optionally a site_id. Keys are case-sensitive and site-level operations are distinct from account-level ones (no automatic merging when you specify site_id).
• Assets, Files, Functions: Uploads target a specific site_id or deploy_id. Asset and file operations return an asset_id or file path which you will use for subsequent queries.
• Hooks, Snippets, Split Tests, Dev Servers: Site-scoped configuration objects managed by their own CRUD endpoints using site_id and object-specific IDs.
• Agent Runners: tied to a site_id and optionally a deploy_id/branch; they produce sessions identified by agent_runner_session_id.

Understanding which ID each operation expects is the most important pattern: account-level calls use account_id or account_slug (they are not interchangeable), site-level calls use site_id, DNS calls use zone_id, and deploy/build calls use deploy_id / build_id.

Entry points — what to call first

• Get the accounts you can act on with listAccountsForUser to obtain account_id and account_slug. Many account-scoped operations reference account_slug (members, listing sites for an account) while some require account_id (env var endpoints, account build status).
• To discover sites, use listSites (global) or listSitesForAccount (scoped by account_slug) to get site_id for the site you will manage.
• To inspect the current site state, call getSite (by site_id). After you have a site_id, other site-scoped resources are reachable: listSiteBuilds, listSiteDeploys, listSiteAssets, listSiteForms, listSiteSnippets, listSiteDevServers.
• To manage DNS, list zones with getDnsZones or create with createDnsZone; use createDnsRecord/getDnsRecords with zone_id once you have the zone.

If a user’s request targets a member, billing, or team action, start with listAccountsForUser and listMembersForAccount (requires account_slug) to find the member IDs to update or remove.

Core workflows you will perform often

Deploy a site (two main flavors):

• Create a deploy directly with createSiteDeploy (supply site_id and optional query flags such as production, branch, deploy-previews). The returned Deploy gives you deploy_id. For file-level uploads, push files using uploadDeployFile (needs deploy_id and the file path) or publish functions with uploadDeployFunction (needs deploy_id and function name).
• Trigger a build with createSiteBuild (use site_id, optional branch, clear_cache, image, template_id, title). Builds produce Build objects and typically result in deploys when finished. Use getSiteBuild to inspect a build (build_id).

Common deploy lifecycle actions:

• Lock/unlock a deploy using lockDeploy / unlockDeploy (pass deploy_id).
• Restore or rollback a deploy with restoreSiteDeploy or rollbackSiteDeploy (site-level operations using site_id and deploy_id where required).
• Cancel or delete a deploy with cancelSiteDeploy or deleteDeploy (use deploy_id).

Upload and manage functions and assets:

• Use uploadDeployFunction for serverless function binaries (supply deploy_id and name). Runtime and invocation options are query params.
• Manage site assets with createSiteAsset (site-scoped), listSiteAssets, getSiteAssetInfo, updateSiteAsset, and deleteSiteAsset. createSiteAsset takes metadata such as name, size, content_type, and optional visibility.

Manage environment variables:

• Account-scoped env vars use createEnvVars, getEnvVars, getEnvVar, updateEnvVar, setEnvVarValue, and deleteEnvVar with account_id. If you provide a site_id query param to these endpoints, you operate on site-scoped values — the API does not perform automatic merging when site_id is used, so specify the scope you intend.
• Keys are case-sensitive. When modifying a specific value entry, use deleteEnvVarValue with the env value id.

DNS and TLS:

• If you need to configure DNS for a site, configureDNSForSite (by site_id) will provision zone association(s); retrieve zone details with getDNSForSite or getDnsZones.
• Create records with createDnsRecord using zone_id. Transfer a zone with transferDnsZone (requires zone_id plus transfer_account_id or transfer_user_id).
• Provision or update TLS with provisionSiteTLSCertificate and read with showSiteTLSCertificate (site-scoped).

Hooks, build hooks, dev server hooks, and snippets:

• List site hooks with listHooksBySiteId (query site_id), create with createHookBySiteId, enable with enableHook, update with updateHook, or remove with deleteHook (pass hook_id).
• Manage build hooks with listSiteBuildHooks, createSiteBuildHook, getSiteBuildHook, updateSiteBuildHook, deleteSiteBuildHook using site_id and hook id.
• Dev server hooks and dev servers follow the same per-site pattern (createSiteDevServer, listSiteDevServers, createSiteDevServerHook, etc.).
• Site snippets live under site_id (create/list/get/update/delete via the snippet endpoints).

Teams, members, and services:

• Add and manage account members with addMemberToAccount (requires account_slug) and updateAccountMember / removeAccountMember (use member_id).
• Service/addon instances are created per-site (createServiceInstance), listed with listServiceInstancesForSite, inspected with showServiceInstance, updated with updateServiceInstance, and deleted with deleteServiceInstance. Service manifests are discoverable through showService / showServiceManifest.

Forms and submissions:

• List site forms with listSiteForms (by site_id), list a form’s submissions with listFormSubmissions (form_id), get individual submissions with listFormSubmission (by submission_id) and remove with deleteSubmission.

Agent Runners and AI sessions:

• Start agent runners with createAgentRunner (query requires site_id, optional deploy_id, branch, agent, model, file_keys), create sessions with createAgentRunnerSession, then track sessions with listAgentRunnerSessions / getAgentRunnerSession.

Non-obvious patterns and gotchas

• account_slug vs account_id: different endpoints require one or the other. listAccountsForUser returns both; choose the identifier the target endpoint expects (memberships and site listing often use account_slug, env var and account-status endpoints use account_id).
• Env var scoping and case sensitivity: Operations that accept site_id behave as site-scoped actions (no merge with account-level vars). Env var key names are case-sensitive—use the exact casing when updating or deleting.
• createSiteBuild branch logic: if you omit branch the build is treated as a production build. If you specify a branch equal to the site’s main branch it is also production; otherwise it is a branch deploy.
• Many create/update endpoints in the spec return a type named Error — that reflects the OpenAPI model rather than runtime failure. Always inspect the returned JSON for the fields you need (IDs, nested objects) rather than assuming a particular wrapper shape.
• Upload endpoints use deploy_id (files/functions) vs site_id (assets). uploadDeployFile expects a path parameter that is the file path inside the deploy; uploadDeployFunction uses name for the function filename.
• Hook and build-hook IDs are sometimes labeled generically as id in the path — be careful to use the hook’s returned id when calling get/update/delete operations.
• DNS transfer requires explicit target identifiers: transfer_account_id and/or transfer_user_id. A transfer is not implicit and must be authorized by the target account/user.
• Agent runner creation takes many options as query params (including agent, model, file_keys, parent_agent_runner_id). Provide the relevant options rather than relying on defaults when the user has specific needs.

Practical shortcuts for common requests

• To perform a deploy from uploaded files: create a deploy (createSiteDeploy) ➜ upload files (uploadDeployFile) for each path ➜ check the deploy with getDeploy.
• To trigger CI-style build runs: call createSiteBuild with optional branch and clear_cache; inspect getSiteBuild until the build completes and yields a deploy.
• To add or update a site environment variable for a single site: call createEnvVars or setEnvVarValue with account_id and site_id (explicit site scope prevents account-level changes).
• To add a team member: use addMemberToAccount with account_slug then verify membership with listMembersForAccount.

When a response looks unexpected

If a response uses the Error-typed wrapper or fields are missing where you expected them, inspect the returned JSON for ID fields (site_id, deploy_id, id, asset_id, etc.). Many endpoints return the data you need even if the OpenAPI name for that response type is non-intuitive. Use the actual JSON fields present in the response to drive follow-up calls (for example, extract site_id from a created Site object to call site-scoped endpoints).

Keep these entity relationships and entry points in mind: accounts → sites → builds/deploys/assets/functions/forms; DNS and TLS are separate resources tied to zones; env vars are account-scoped with optional site override. That map covers the majority of user requests you will encounter and lets you pick the right operation and ID to call next.