API

The ActiveState Platform API enables you to programmatically build complex open source software for different operating systems and languages without managing your own infrastructure. The API uses GraphQL, providing precise control over the data you request and receive.

Quick Links:

In this article:

Authentication

Example Queries

Authentication Process

Both authentication methods require the State Tool CLI to be installed and your account to be authenticated with the state auth command.

If you have not authenticated using state auth, your browser will open prompting you to authorize your State Tool. If the prompt does not appear, paste the link from the state auth output into your browser and click Authorize.

After authenticating with the State Tool CLI, you can authenticate with the GraphQL console using either:

  • JSON Web Tokens (JWTs) - Temporarily issued tokens that expire after a set period
  • API keys - Persistent credentials that do not expire

Protect your account by never sharing or publicly displaying your API key.

Generate a JWT

state export jwt

Generate an API Key

state export new-api-key <orgname/projectname>

Add Authentication to GraphQL Console

In the “Header” section of the GraphQL console, enter your token:

{
  "Authorization": "Bearer "
}

Example Queries

Example 1: Query to return basic information about an ActiveState Project

This example demonstrates using GraphQL variables to create reusable queries.

Open this pre-populated query in the GraphQL console or copy the query below:

query project(
  $organization: String!, 
  $project: String!
) {
  project(
    organization: $organization, 
    project: $project
  ) {
    ... on Project {
      name
      description
    }
    ... on NotFound {
      message
    }
  }
}

Add the following information into the “variables” section of the GraphQL console as seen in the screenshot further below:

{
  "organization": "activestate-doc-examples",
  "project": "graphql-query-sample-1"
}

alt_text

Execute the query with Ctrl+Enter or click the play button.

Example 2: Query Project Build Expression

This query retrieves the build expression for a specific commit.

query commit {
  commit(commitId: "49a44671-6434-4821-8131-ec6ea7acd029") {
    ... on Commit {
      expr
    }
    ... on NotFound {
      message
      type
    }
  }
}

Open in GraphQL Console

Response:

{
  "data": {
    "commit": {
      "expr": {
        "let": {
          "sources": {
            "solve": {
              "at_time": "2023-11-06T19:15:03.030000Z",
              "platforms": [
                "46a5b48f-226a-4696-9746-ba4d50d661c2",
                "78977bc8-0f32-519d-80f3-9043f059398c",
                "7c998ec2-7491-4e75-be4d-8885800ef5f2"
              ],
              "requirements": [
                {
                  "name": "python",
                  "namespace": "language",
                  "version_requirements": [
                    {
                      "comparator": "eq",
                      "version": "3.10.13"
                    }
                  ]
                },
                {
                  "name": "appdirs",
                  "namespace": "language/python"
                },
                {
                  "name": "flask",
                  "namespace": "language/python"
                },
                {
                  "name": "scipy",
                  "namespace": "language/python"
                }
              ],
              "solver_version": null
            }
          },
          "runtime": {
            "state_tool_artifacts_v1": {
              "src": "$sources",
              "build_flags": []
            }
          },
          "in": "$runtime"
        }
      }
    }
  }
}

Example 2: Query to return a project build expression

query commit {
  commit(commitId: "49a44671-6434-4821-8131-ec6ea7acd029") {
    ... on Commit {
      expr
    }
    ... on NotFound {
      message
      type
    }
  }
}

Open in GraphQL

Response:

{
  "data": {
    "commit": {
      "expr": {
        "let": {
          "sources": {
            "solve": {
              "at_time": "2023-11-06T19:15:03.030000Z",
              "platforms": [
                "46a5b48f-226a-4696-9746-ba4d50d661c2",
                "78977bc8-0f32-519d-80f3-9043f059398c",
                "7c998ec2-7491-4e75-be4d-8885800ef5f2"
              ],
              "requirements": [
                {
                  "name": "python",
                  "namespace": "language",
                  "version_requirements": [
                    {
                      "comparator": "eq",
                      "version": "3.10.13"
                    }
                  ]
                },
                {
                  "name": "appdirs",
                  "namespace": "language/python"
                },
                {
                  "name": "flask",
                  "namespace": "language/python"
                },
                {
                  "name": "scipy",
                  "namespace": "language/python"
                }
              ],
              "solver_version": null
            }
          },
          "runtime": {
            "state_tool_artifacts_v1": {
              "src": "$sources",
              "build_flags": []
            }
          },
          "in": "$runtime"
        }
      }
    }
  }
}

Example 3: Building Queries with GraphiQL Autocomplete

This walkthrough demonstrates using GraphiQL’s autocomplete features to explore the API schema and construct queries.

Navigate to the GraphQL console.

  1. Navigate to https://platform.activestate.com/sv/buildplanner/graphql.

  2. Start with a basic query structure:

Basic query structure

  1. Use Shift+Spacebar to view available top-level fields:

Available fields

  1. Select project. GraphiQL will underline the field to indicate missing required arguments. Hover over the field to view requirements:

Required arguments

  1. Add the required org and name arguments:
project(org: "ActiveState", name: "ActivePython-3.8")
  1. Add a selection set with inline fragments. Use Shift+Spacebar to explore available fields:

Available project fields

  1. Select fields like description and private to complete your query:

Complete basic query

The response structure mirrors your query structure. In this example, the response includes the project description and privacy status (false indicates a public project).

  1. Extend the query by adding fields like lastEdited, created, and managed:

Extended query

Execute queries with Ctrl+Enter or the play button. Access previous queries via the History tab in the left sidebar.