Scripts in Major Tom are extremely powerful. They allow you to automate routine actions, react to Events, and generally add intelligence to your ground operations.

The Major Tom Scripting API uses GraphQL, an expressive typed query language. You may send GraphQL queries and mutations over raw HTTP POST requests or with a GraphQL client in your language of choice. All responses will be in JSON, in accordance with the GraphQL spec.

To use the API, first create a new Script in Major Tom, which will provide you with a Script Authentication Token. You will provide this token in the X-Script-Token HTTP header whenever you interact with the Scripting API.

Response Codes

If the provided Script Authentication Token is invalid, you will receive a 403 response.

If the Script is temporarily disabled, as is possible to do in the Major Tom UI, you will receive a 422 response.

If your instance of Major Tom requires HTTP Basic Access Authentication and you have provided an invalid one, you will receive a 401.

If your instance of Major Tom is undergoing maintenance, or is otherwise temporarily unavailable, you may receive a 404 or 503 error. You should wait a few seconds and try again.

RATE_LIMIT_MESSAGE If your Script has reached its request rate limit, you will receive a 420 response. When receiving this error, look at the X-RateLimit-RetryAfter header to see how many seconds you must wait before the next request will be accepted.After any request, you can also look at the X-RateLimit-Rate and X-RateLimit-Remaining headers to see the average allowed request rate per minute and number of requests remaining before a rate limit will be triggered.

GraphQL Playground and API Documentation

This documentation is largely duplicated inside of Major Tom itself, but is accompanied by auto-generated references for individual available queries and mutations, as well as an interactive "playground." Inside Major Tom, once you've created a Script and select it from the left-hand slide-out list of scripts, you'll be at the Script's Settings page. At the top are several small sections for configuring the Script, followed by a long section titled "Scripting API Documentation." In the upper-right corner of the section containing the documentation is a blue button labeled "GraphQL Playground".

The Playground can be used to explore the Schema, Documentation, and execute Queries and Mutations against the MajorTom API. It’s recommended to test any Queries or Mutations in a Development mission before promoting them to a Production mission.

Code Examples

For code examples and a Python API wrapper, please see our repo of Example Major Tom Scripts.

GraphQL: Re-create the Communication Tab

Executing Queries

As an example, let's request information about the current Script from the Major Tom Scripting API using a GraphQL query:

*1* query CurrentAgent {
*2*  agent {
*3*    type
*4*    script {
*5*      id
*6*      name
*7*      mission { id }
*8*    }
*9*   }
*10* }

You can run this query with curl, a client of your choice, or with the GraphQL Playground button in the upper right of this documentation section. Here is how you would run it with curl: