I’m building a Vercel integration that uses Vercel REST API. In doing so, I’ve encountered a few endpoints that are either not properly documented or not working at all. I’ve managed to find some workarounds by inspecting how the Vercel Dashboard interacts with some of these endpoints. But these hacks are even more imperfect, so I thought I’d ask in hopes of finding proper solutions.
Endpoint to list deployment files is not working at all, a request to it usually takes about 3 minutes until it eventually responds with 500 Internal Server Error. As a solution for this, I’ve started using some endpoints to vercel.com/api instead of api.vercel.com. But I’m not sure if that’s allowed or the correct approach.
Endpoint to get deployment file contents is also not working at all. But I’ve discovered that if you use get in place of {fileId} and pass in path={encoded file path} as a query parameter, it seems to respond for some files which I refer to as v7 files.
Some files need to be read through undocumented v6 endpoint and requires outputs instead of get in {fileId} and file instead of path query parameter. But only some files work through v6 API. I don’t know which files are v6 and which are v7. Both of these APIs respond wildly differently.
The teams endpoint is unavailable for tokens obtained through Vercel Integrations OAuth. I suspect I need to configure my integration to access it, but I haven’t been able to figure out how.
These are the major blockers I’m facing. There are also minor issues like incorrect or undocumented field names and value types in the documentation, but those were easier to debug and work around.
It’s awesome to hear about the VSCode extension that you’re building! I’d love to continue to hear the progress that you’re making on it - feel free to keep sharing.
Actually would love to get your thoughts on something we’re launching soon - I’ll send you over a private message.
Is there an API where I can get the team ID of an access token? My use case is that I recently added manual access token authentication mechanism. But these tokens can be generated to have access to only a single team. In that case I’d need to get a team ID as all the endpoints for projects or deployments under a team seem to require it. I found access token metadata API but it doesn’t return team ID.
Am I right to assume that teamId is always required for projects under teams (that is not the user’s defaultTeam), do I need to always pass it in? I currently don’t. I’ll have to fix a ton of my logic in it’s required haha.
EDIT: For example currently vscode-vercel://deployments/$deploymentId/$name.log will open build logs as a file. If teamId is required that means I’ll have to restructure the URL so that teamId is also included.
Does it mean the endpoint will stream the response? Or something else? My deployments finish too fast for me to test it out. I’m trying to implement real time build logs view.
Hello, another question, is there any documented spec on Vercel’s IDs? For example, I currently know that teamId, projectId and deploymentId are case-sensitive and can contain the alphabet, digits and an underscore.
My use case is I’m trying to embed them into an URI and, because URIs can be both case-sensitive and insensitive depending on OS (macOS - insensitive, Linux - sensitive etc), I’ll have to encode these IDs and replace uppercase letters with alternative letters. So I kinda need to know what characters won’t be included in these IDs (and also length). Thanks!
Thank you for your question about Vercel’s ID formats. I reached out internally for clarification, and here’s what I learned:
deploymentId uses base58 encoding
teamId is a custom UID
projectId is also a custom UID
While Vercel uses base58 for many of our ID generations, it’s not guaranteed for all entities. However, there is a shared character set across all IDs, which is:
This means that all Vercel IDs will only contain these characters, regardless of their specific type.
For your use case of embedding these IDs into URIs, you should be aware that URIs can be case-sensitive. Since these IDs can contain both uppercase and lowercase letters, you’ll need to handle this carefully when encoding them for use in URIs.
Is there an API to retrieve the team ID from an access token?
No, the teamId is stored internally within the scope of the token, but there is no API available to directly request the scope of a token.
Is the teamId always required to access projects under a team (when it’s not the user’s default team)?
Yes, the teamId is always required when accessing single resources by their ID.
Does the current lack of a required teamId in the URL structure imply they need to restructure their URLs?
Yes, as mentioned earlier, accessing single resources by ID almost always requires the teamId. Including the teamId in the URI representation could be a good approach since there are no plans to change this requirement in the foreseeable future.
