Skip to content
Docs

Make Your First Vercel API Request

Use a Vercel access token to call the Vercel REST API with curl, then make the same request with @vercel/sdk. Both examples retrieve at most one project with GET /v10/projects and do not change your account.

Prerequisites

  • A Vercel account
  • A terminal with curl
  • An active Node.js LTS release and npm for the SDK steps

Choose REST or the SDK

Both approaches call the same Vercel REST API operation and use the same access token:

ApproachWhen to use it
REST with curlYou want to call the API directly from a shell or another HTTP client.
@vercel/sdkYou are using TypeScript or JavaScript and want generated methods and types.

Complete both examples to confirm that your token works with direct HTTP requests and the SDK.

Create a scoped access token

Access tokens are secrets. Do not commit a token to source control or share it in logs and screenshots.

  1. Open the Account Tokens page

    Go to the Account Tokens page and enter a descriptive name for the token.

  2. Choose the token scope and expiration

    Choose the narrowest scope that covers the projects you need to access with the API. The project-list operation works with Full Account, Team, and Project scopes. Then choose an expiration and select Create.

    See access token scopes for the full behavior of each option.

  3. Store the token in your shell

    Copy the token when Vercel displays it. You cannot view its value again after leaving the page.

    In a bash or zsh terminal, run the following command. Paste the token when the terminal waits for input, then press Enter:

    terminal
    read -s VERCEL_TOKEN && export VERCEL_TOKEN

    The shell does not display the token. Keep this terminal open for the remaining steps.

Make a request with curl

Send a GET request to /v10/projects. The limit=1 query parameter limits the response, and the command saves the JSON body to vercel-projects.json:

terminal
curl --fail-with-body --silent --show-error \
  --output vercel-projects.json \
  --write-out "HTTP %{http_code}\n" \
  "https://api.vercel.com/v10/projects?limit=1" \
  --header "Authorization: Bearer $VERCEL_TOKEN"

A successful request prints the following status:

HTTP 200

The response body can be a project array or a paginated object with projects and pagination. See the project-list response reference for every field.

Make the same request with @vercel/sdk

  1. Create a Node.js project

    Create a directory and install the Vercel SDK:

    terminal
    mkdir vercel-api-quickstart
cd vercel-api-quickstart
npm init --yes
npm install @vercel/sdk

    npm creates a package.json file and adds @vercel/sdk as a dependency.

  2. Add the SDK request

    Create an index.mjs file with the following code:

    index.mjs
    import { Vercel } from '@vercel/sdk';
 
const bearerToken = process.env.VERCEL_TOKEN;
 
if (!bearerToken) {
  throw new Error('VERCEL_TOKEN is not set');
}
 
const vercel = new Vercel({ bearerToken });
const result = await vercel.projects.getProjects({ limit: '1' });
const projects = Array.isArray(result) ? result : result.projects;
 
if (projects.length === 0) {
  console.log('Success: no projects in this token scope');
} else {
  const project = projects[0];
  console.log(`Success: ${project.name} (${project.id})`);
}

    In TypeScript, getProjects returns Promise<GetProjectsResponseBody>. The response type can be a project array or a paginated object, so the example normalizes both forms before reading the first project.

  3. Run the SDK request

    Run the script from the same terminal where you exported VERCEL_TOKEN:

    terminal
    node index.mjs

    If the token scope contains a project, the script prints a project name and ID:

    Success: my-project (prj_xxxxxxxxxxxxxxxxxxxxxxxx)

    If the scope contains no projects, the script still confirms that the request succeeded:

    Success: no projects in this token scope

Understand account, team, and project scope

The token scope determines which projects GET /v10/projects can return:

Token scopeRequest targetteamId or slug behavior
Full AccountYour personal account by default, or a team you belong toOmit both for personal projects. Pass either value to target a team.
TeamProjects in the token's teamOmit both. Vercel infers the team from the token.
ProjectThe token's single projectOmit both. Vercel infers the team and project from the token.

A project-scoped token denies requests for user-level resources, team-level resources, and other projects. See access tokens for token creation and scope details.

Handle common 401, 403, and 429 responses

StatusCauseWhat to check
401 UnauthorizedThe API did not accept the authentication details.Confirm that VERCEL_TOKEN is set and the header uses Authorization: Bearer <token>.
403 ForbiddenThe token does not have permission to access the requested resource.Check the token's expiration and scope. For a full-account token targeting a team, pass teamId or slug.
429 Too Many RequestsA platform-wide API rate limit rejected the request.Reduce the request rate and retry after the limit resets.

See REST API errors for error payloads and API rate limits for limit scopes and reset behavior.

What you learned

You authenticated with a Bearer token, called the read-only GET /v10/projects operation with curl, and called the same operation with vercel.projects.getProjects. You also learned how Full Account, Team, and Project token scopes affect requests.

Explore the reference

Was this helpful?