Last updated Aug 17, 2022

Rate this page:

Create components using the API

You can create components using the Compass GraphQL API by:

  1. Logging into the GraphQL API explorer
  2. Looking up the unique cloudId for your Atlassian site
  3. Creating the new component using the cloudId

Log in to the GraphQL API explorer

  1. Go to the GraphQL API explorer.
  2. Log in with your Atlassian account if you are prompted to do so.

Look up the unique cloudId for your Atlassian site

  1. In the GraphQL API explorer, enter this code into the query area on the left side:
    1
    2
    query getCloudId($hostName: String!) {
      tenantContexts(hostNames: [$hostName]) {
        cloudId
      }
    }
    
  2. From the bottom left corner of the screen, select Query variables and enter this code, substituting the hostName value with your Atlassian site hostname:
    1
    2
    { "hostName": "your-site-hostname.atlassian.net" }
    
  3. From the top navigation of the GraphQL API explorer, select Execute query
    • The cloudId for your site appears in the results area on the right side.
  4. Copy the value of the cloudId to your clipboard.

Create a new component

Use the createComponent mutation to create the new component.

  1. In the GraphQL API explorer, enter this code into the query area on the left side:
    1
    2
    mutation createComponent($cloudId: ID!, $componentDetails: CreateCompassComponentInput!) {
      compass {
        createComponent(cloudId: $cloudId, input: $componentDetails) {
          success
          componentDetails {
            id
            name
            type
          }
        }
      }
    }
    
  2. From the bottom left corner of the screen, select Query variables and enter this code:
    1
    2
    {
      "cloudId": "your-cloudid",
      "componentDetails": {
        "name": "your-component-name",
        "type": "your-component-type"
      }
    }
    
  3. Substitute your cloudId and the name of the new component.
  4. Substitute the type with your component’s type. The valid values are APPLICATION, LIBRARY, SERVICE and OTHER.
  5. From the bottom left corner of the screen, select Request headers and enter this code:
    1
    2
    { "X-ExperimentalApi": "compass-beta" }
    
    • Compass is in beta, so you must use this header with all Compass API requests.
  6. From the top navigation of the GraphQL API explorer, select Execute query
    • You'll see the id, name and type of your newly created component in the results area on the right side.

Components have more attributes other than name and type. For a complete list of input parameters to create components using the API, see the createComponent mutation in the Compass GraphQL API reference documentation.

Troubleshooting

If you get an error when attempting to create the component, make sure you’ve provided:

  • the entire cloudId for your Atlassian site and there are no typos
  • values for name and type, which are both mandatory
  • a valid option (APPLICATION, LIBRARY, SERVICE or OTHER) for type

Learn more

You can perform numerous other operations using the Compass GraphQL API. To learn more, see the following resources:

Rate this page: