Teams API: A First Request Walkthrough

The Stack Exchange API permits read and write access to data within private Teams. 

Note: Only Stack Overflow Business accounts have read and write access to the API. Other Stack Overflow for Teams accounts are limited to read access. 

You'll need to register on the Stack Apps site to get a client ID and key, which will in turn be used to generate an access token via OAuth. This will allow you to make read-only requests for your Team data. There's a few things to keep in mind:

  • The Teams API has a few routes missing that don't apply to Teams-specific items. 
  • The team parameter is required, and will be stackoverflow.com/c/<team name> (URL encoded)
  • Only OAuth is permitted, which means
    • you need to register for a write API key 
    • a scope for a given team must be set (scope=access_team|stackoverflow.com/c/<team name>)
    • tokens scoped for a Team will not be allowed access to the public site

How do I get access to the Teams API?

At a high level:

  • Create an account on Stack Apps (so we can link up to your account and identify your Teams membership)
  • Create a Stack Apps application and note its properties
  • Acquire API credentials via OAuth
  • Make Teams requests

Walkthrough of your first Teams API request

  • Create an account on Stack Apps

  • Create an application

    • Name it.
    • Assign an OAuth domain to which you'll be redirected with your access token (for testing, you'll be able to use https://stackexchange.com/oauth/login_success for the redirect_uri).
    • Add a web site where users can read more about your creation.
    • Enable client-side OAuth Flow.
    • You'll get some credentials and properties which we'll use going forward:
    • Client Id This Id identifies your application to the Stack Exchange API. Your application client id is not secret, and may be safely embedded in distributed binaries. Pass this as client_id in our OAuth 2.0 flow.
    • Client Secret We won't need this for our test API request, as we'll be using the implicit path. Still, make sure you keep this a secret!
    • Key Pass this as key when making requests against the Stack Exchange API to generate OAuth access tokens and receive a higher request quota. This is not considered a secret, and may be safely embedded in client side code or distributed binaries.
    • Client Side Flow Is Enabled If this is disabled, please Edit the app and enable it. This is what permits the implicit grant OAuth flow used in this walkthrough.
    • Desktop OAuth Redirect Uri is Enabled Assure this is enabled, which lets you use https://stackexchange.com/oauth/login_success as the redirect_uri.
    • If you forget any of these properties, you can revisit your apps on the Stack Apps site.
  • Generate an Access Token via OAuth

    • Make a request to https://stackoverflow.com/oauth/dialog?client_id=<client_id>&scope=access_team|stackoverflow.com/c/<team name>&redirect_uri=https://stackexchange.com/oauth/login_success
    • Approve your application
    • You'll be redirected to https://stackexchange.com/oauth/login_success and your access token and expiration time in seconds will be appended as URL parameters. Snag those out of the URL (example: https://stackexchange.com/oauth/login_success#access_token=\<gibberish\>&expires=86400)
  • Make your first request!

    • Put together a request that gets you what you want on the API Explorer. For example, you can get a page of questions from your Teams site.

    • Right-click and Copy the URL out of the "Run" box (it should come with the full URL if you copy) and tack on the following query parameters: &key=<key from the application you created>&team=stackoverflow.com/c/<team name>

    • Set the X-API-Access-Token Header in the request to the access token you retrieved via OAuth.

    • Don't forget to URL encode the parameters. For example, / becomes %2f in the team parameter.

    • Stack Overflow compresses all responses by default, either with GZIP or DEFLATE, and your tool of choice will need to be able to unzip the response

    • Examples

    • curl -XGET --header "X-API-Access-Token: <access token>" 'https://api.stackexchange.com/2.2/questions?order=desc&sort=activity&site=stackoverflow&team=stackoverflow.com%2fc%2f<team name>&key=<your key>' | gunzip
      
    • powershell (Invoke-WebRequest 'https://api.stackexchange.com/2.2/questions?order=desc&sort=activity&site=stackoverflow&team=stackoverflow.com%2fc%2f<team name>&key=<key>' -Headers @{"X-API-Access-Token"="<access token>"}).Content | ConvertFrom-Json | ConvertTo-Json 

And Bob's your uncle! Well, probably not, but if they are, tell Bob we said hi and that we're really happy you've taken the first step in getting Teams information through the API.