Get started

The most effective way to begin working with the Ballpark Web API is by using our API Explorer. This interactive environment introduces you to GraphQL concepts and helps you understand the full range of operations available within the Ballpark API.

If you already have a specific integration or workflow in mind, you may wish to start with the tutorials to see if your use case is covered. Once you are comfortable, you can proceed with authentication and begin making calls directly from your own code.

Exploring the API

You can experiment with the API via the GraphQL Explorer at ballparkhq.com/graphql.

• Your query editor is located on the left.

• The response window is in the middle.

• The documentation explorer is on the right, showing available queries, mutations, fields, arguments, and data types.

This is the recommended way to explore the API. However, please note that this environment operates against live production data—any changes made here will immediately affect your Ballpark account.

For a general introduction to GraphQL itself, refer to graphql.org/learn.

Authentication

Ballpark uses OAuth access tokens to secure API requests.

• For local development or internal scripts, you can generate a personal access token at /oauth/devtoken.

• For production applications, refer to the Authentication guide to implement a full OAuth flow.

Making API Calls from Code

The Ballpark API communicates entirely over HTTP. To issue a request:

1. Send a POST request to the GraphQL endpoint:

   https://api.ballparkhq.com/graphql/

   
   

2. Include a Content-Type: application/json header.

3. Pass your GraphQL query (or mutation) as a JSON payload under the query key.

4. If your query uses variables, include them under the variables key.

5. Provide an Authorization header containing your access token.

Example (using curl):

curl \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -X POST -d '{ "query": "query getUser { user { email username } }" }' \
  https://api.ballparkhq.com/graphql/

Introspecting the Schema

One of GraphQL’s greatest strengths is its introspection capability. Unlike many REST APIs with incomplete or outdated documentation, GraphQL allows you to query the schema directly.

By running an introspection query, you can retrieve a machine-readable description of every node, edge, and connection in the Ballpark API schema. This is the same data used by the GraphQL Explorer to power autocomplete and typeahead functionality.

Although the raw results may not be human-friendly, they are invaluable for tooling and client libraries, enabling richer development experiences with minimal reliance on static documentation.