Tags | API |

This documentation is for Stack Overflow for Teams Enterprise. Free, Basic, and Business users can access their documentation here. Find your plan.

The Stack Overflow for Teams API enables you to interact with your Stack Overflow Enterprise (SOE) site programmatically with external scripts, reporting tools and automated workflows. API v3, the third version of our API, builds on API v2 with new capabilities and an updated interface.

API v3 now allows access to subject matter experts (SMEs), user groups, and private teams. With these new endpoints, you can:

You'll access API v3 within your SOE instance at https://[your_site]/api/v3. API v2 is still available at https://[your_site]/api/docs, but we recommend using API v3.

In addition to this document, https://[your_site]/api/v3 has interactive documentation with definitions for all API v3 methods and data models. 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.

If you'd like to use API v3 and aren't yet on the latest release, please reach out to support to schedule an upgrade of your site.

THIS ARTICLE APPLIES TO STACK OVERFLOW FOR TEAMS ENTERPRISE ONLY.
Other Stack Overflow for Teams users should read this article instead. Find your plan.

The starting point for API v3 authentication is the API Application. This authorizes the creation of API access tokens through an OAuth process. The resulting access token accompanies and authorizes 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. Only users authenticated into SOE can create API Applications and tokens.

NOTE: 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.

In addition to its write permissions scope (read-only or read-write), each API v3 token has a private team or main site scope. If you specify a private team when creating a token, that token will be able to access only that team and not the main site data. Likewise, a main site token (no private team specified) can't access private team data. Only users who are part of a private team can use a private team token to access that team's data.

API v3 uses OAuth authentication to generate access tokens. This OAuth flow requires the API application to specify the domain of the application that will be accessing the API. If successful, the OAuth authentication process returns the resulting access token to the specified domain. Learn more about API applications and tokens from your on-site API v2 documentation at https://[your_site]/api/docs/authentication.

Like API v2, API v3 supports two types of API applications: user API applications and service keys. A user API application is user-specific, being associated with the user that created it. Only that user can use the API application to create an access token.

A service key is a special type of global API application, created by an administrator and owned by the "Community" user. Because it's not tied to a specific user, a service key is useful for creating an API application that's available to all users in a company.

To manage API applications and service keys from the admin API settings page, click Admin Settings then API under the "INTEGRATION AND APPS" heading. This page shows a table of existing API applications from particular users and the service keys (owned by the "Community" user).

Click on any column heading to sort the table by that column. To view only service keys, select Service Keys from the right-most pull-down menu at the top of the table.

NOTE: Administrators can also create user API applications if they plan to access API v3 for their own purposes.

Only admins can create API v3 service keys. To create a new service key, click Create new service key. The Community user page will appear.

Create the new service key with this process:

Once done, the new service key will appear in the "Active API applications" list for the Community user.

All new API applications, including service keys, start with read-only permissions. To change the permissions of a service key, click its select menu in the Status column.

When changing a service key's status to Read-write, SOE will prompt you for a Permitted Domain. Enter the domain of the application that will be accessing the API and click Confirm.

To change a read-write service key to read-only status, click its Status select menu and select Read-only. Click Disable. To remove a service key entirely, click its trash can (delete) button.

Unlike service keys, which all users can use, user API applications are only valid for the user that created them. If that user is removed from the site by deactivation or deletion, any user API applications they created will no longer work.

An API application's token has access to the same data as the user that created it. An access token with read-write permissions, for example, can update the same content (questions, answers, comments) as the user.

To access the user API application management page, click your avatar (profile picture) at the top of the page. Click Settings, then API applications (under the "APPS & INTEGRATIONS" heading).

The API application page has two parts: an upper section to create new API applications, and a table of existing API applications below.

To create a new user API application, enter an API application name and your site's Domain. Click Create API application. Your new API application will appear in the "Active API applications" table.

To change the permissions of an API application, click the select menu in that API application's Status column. When you enable write access, you'll be prompted to enter or confirm the domain of the application that will be accessing the API. To delete an API application, click its trash can (delete) button. The API will reject any future calls that use the deleted API application.

The API application table on the admin settings page allows control over user API applications as well as service keys. Admins can change the read-only/read-write scope of any user API application, update its domain, and delete it.

If you create an API key with read-write access, you can use it to perform write operations. This includes submitting and editing questions and answers, as well as voting and editing. The site credits these actions to the user that the API key belongs to, so don't share your write-enabled API key with other users.

When reading or writing a post, the API applies HTML encoding to the body and body_markdown data. This renders symbols such as the quote character into " and the > character into >. This encoding rarely affects simple text posts, but it can have a negative impact on complex posts with links, lists, and special symbols.

It's especially important to remember HTML encoding when using the API to update a post by reading, editing, and writing. Since the API encodes HTML entities during the read operation and the write operation, entities will be double-encoded if you don't perform an HTML decode after the initial read. Double-encoded HTML entities (such as ") will often break the display of the post.

SOE's interactive API v3 documentation (Swagger UI) is disabled by default. Admins can enable it by scrolling to the bottom of the API applications page and clicking On. When you enable Swagger UI, SOE creates a service key for it. If you later disable Swagger UI, SOE will delete the Swagger UI service key.

To access the interactive documentation, click Go to Swagger UI (or navigate to https://[your_site]/api/v3). To download a JSON file of all API v3 endpoints and models, click Download.

API v3 uses the same OAuth process as API v2 to create access tokens from API applications. Go to https://[your_site]/api/docs, and follow the instructions in the "Authentication" section. Choose the explicit or implicit grant flow based on your API application. To generate read-only tokens, omit "write_access" from the scopes list. To create a token for private team access, include the "access_team" scope. To make a token that never expires, include "no_expiry".

The Swagger UI interface functions as a service key with full access to API v3 as the authenticated user. When authorized, Swagger UI uses its service key to create an access token. You can also use this token for API calls outside of Swagger UI, which may be useful for temporary API application development or testing. An access token created through Swagger UI expires after 24 hours.

NOTE: If you already have an active Swagger UI access token, first delete this token so you can make changes and reset the 24-hour expiration window. Do this by clicking Authorize, then Logout, then Authorize again.

To authorize Swagger UI and create a new access token:

When you use Swagger UI to access API v3, Swagger UI reveals the access token as part of the underlying API call. You can find the access token in the "Curl" section of the Swagger UI execution output. Look for the following line:

SOE 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.

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:

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 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:

If you have questions or issues, reach out to our support team for help.

If you need further support or have questions, contact your site administrator.