Tags | API |
The Stack Overflow for Teams API enables you to interact with your Stack Overflow for Teams site programmatically with external scripts, reporting tools, and automated workflows. Version 3 of our API builds on API v2 with new capabilities and an updated interface.
API v3 now allows access to subject matter experts (SMEs) and user groups. With these new endpoints, you can:
Get or update SMEs for a tag.
Add or remove users or user groups as SMEs.
Create user groups and add or remove members.
In addition to this document, API v3 has interactive documentation with definitions for all methods and data models at https://api.stackoverflowteams.com/v3. This interactive documentation system (Swagger UI) allows you to test API calls and view returned data in a convenient web interface with no API implementation required. API v3 uses modern API design patterns, making it easy and familiar for both developers and end users.
Authentication and Authorization
API v3 uses personal access tokens (PATs) to authorize API requests. You'll create one or more PATs to access API v3, and then provide a PAT with each API v3 request. Access tokens that are read-only can read data only; read-write tokens allow API calls to read, update and delete data (Business tier only). Only users authenticated into Stack Overflow for Teams can create PATs.
NOTE: Stack Overflow for Teams Basic has read-only access to API v3, while Stack Overflow for Teams Business has read/write access.
You can use the same API access tokens for API v2 and v3 requests. Each token's write permissions scope (read-only or read/write) applies to both APIs.
Learn more about access keys and tokens from your on-site API v2 documentation at https://api.stackoverflowteams.com/docs/authentication.
Personal access tokens (PATs)
A PAT authorizes an external API application to access data on your behalf, and it grants access only to the data that you can see as a user. A PAT with read-only permissions, for example, can view the same content (questions, answers, comments) as you, and only in the team specified on creation.
To create and manage your PATs, click your avatar (profile picture) at the top of the page. Click Account Settings, then Personal access tokens (under the "API" heading). The "Personal access tokens (PATs)" page appears, listing existing tokens.
To create a new token, click Create a new PAT. The "Create a personal access token" box appears with the following fields:
PAT Description Use this field to give your PAT a name that's useful and recognizable to you.
Team scope Select the team that this PAT can access. NOTE: each PAT can access only one team.
Expiration Date Set the duration the PAT will be valid. For security, we recommend setting an expiration for all PATs.
Enable write access (Business only) Check this box to give the PAT read and write access.
When you first create a PAT, its code will appear in the PAT list. Stack Overflow for Teams won't display the code again, so be sure to copy and save it for later use in your API integration.
If you don't save the code for a new PAT, you can't use it. You'll have to delete the PAT and create it again.
To delete a PAT from the list, click its Delete link.
Swagger UI authorization
The Swagger UI interface functions as an API application with full access to API v3 as the authenticated user. When authorized, Swagger UI uses its access key to create its own PAT code. You can use this code for API calls outside of Swagger UI, which may be useful for temporary API application development or testing.
Your PAT list will show a PAT ("Created by Swagger UI") for each team you authorize Swagger UI to access. PATs created through Swagger UI expire after 24 hours.
If you already have an active Swagger UI PAT, you should refresh the token to reset the 24-hour expiration window. Do this by clicking Authorize, then Logout, then Authorize again.
To authorize Swagger UI:
Click Authorize. An "Available authorizations" box will appear.
Leave Client ID unchanged.
Check write_access if the token should have write permissions (Business only).
Check access_team. Choose the private team and click Continue.
When you use Swagger UI to access API v3, Swagger UI reveals its PAT code as part of the underlying API call. You can find the code in the "Curl" section of the Swagger UI execution output. Look for the following line:
-H 'Authorization: Bearer [PAT code]))'
Stack Overflow for Teams API v3 uses request throttling to prevent abuse and ensure optimum performance for all API users. We currently implement two different types of throttling to alleviate excessive API calls over both short and long time intervals. Both monitor the number of requests coming from each access token.
Burst throttle rate limiter
The burst throttle rate limiter engages when an access token makes too many requests during a brief window of time. The default for this limiter is 50 requests in a two-second interval.
The burst throttle rate limiter returns two headers with information about throttling status:
x-burst-throttle-calls-left The number of calls left in the time window before the throttle begins rejecting API calls.
x-burst-throttle-seconds-until-full The number of seconds left in the throttle time window.
Token bucket rate limiter
As its name implies, API v3's token bucket rate limiter manages a "bucket" of request tokens. Each API request consumes a token from the bucket. When API requests consume all the tokens in the bucket, API v3 will reject subsequent requests. API v3 refills the bucket with a set number of tokens each second. When the request token bucket is full, API v3 stops adding tokens. The default max tokens setting is 5000, with a refill rate of 100 tokens every 60 seconds.
API v3 responses include three headers with information about the token bucket rate limiter status:
TokenBucket_MaxTokens The maximum number of tokens the bucket will hold (when the API will stop adding tokens).
TokenBucket_RefillSeconds The interval of time between refills.
TokenBucket_RefillTokens The number of tokens the API adds at each refill.
Need help? Submit an issue or question through our support portal.