Get Started

Before we start, you will need an account on ScreenCloud Studio. If you don't have an account yet, you can sign up for a free trial.

Once logged in, you will also need to get an API token.

Quickstart

You will first want to download and install a GraphQL browser. These expose a simple GUI where you can type requests in GraphQL on the left, and receive JSON responses from an API on the right.

The simplest query just fetches a single field. Type the following in your GraphQL browser of choice.

query {
  currentOrgId
}

Hit send, and the API will dutifully reply (though with a different value for currentOrgId):

{
  "data": {
    "currentOrgId": "3fd0011c-b6c2-4cc9-92ba-2e1474401fa4"
  },
  "meta": {
    "graphqlQueryCost": 1
  }
}

This in itself is not terribly useful. After all, you can just read this from Studio account settings. But it does mean you've successfully made a GraphQL query.

Let's try something a bit deeper:

query {
    currentOrg
}

We expect this to return a JSON body with the data fetched.

Except this particular call will give a 400 Bad Request error. Why? The returned JSON gives us a clue:

{
  "errors": [
    {
      "message": "Field \"currentOrg\" of type \"Org\" must have a selection of subfields. Did you mean \"currentOrg { ... }\"?",
      "locations": [
        {
          "line": 6,
          "column": 3
        }
      ],
      "stack": "GraphQLError: Field \"currentOrg\" of type \"Org\" must have a selection of subfields. Did you mean \"currentOrg { ... }\"?\n    at Object.Field (/app/dist/server.js:364182:41)\n    at Object.enter (/app/dist/server.js:356613:41)\n    at Object.enter (/app/dist/server.js:356650:33)\n    at visit (/app/dist/server.js:356546:34)\n    at Object.validate (/app/dist/server.js:363576:28)\n    at parseQuery (/app/dist/server.js:455092:48)\n    at /app/dist/server.js:455275:61\n    at Array.map (<anonymous>)\n    at requestHandler (/app/dist/server.js:455247:52)\n    at runMicrotasks (<anonymous>)\n    at processTicksAndRejections (internal/process/task_queues.js:97:5)"
    }
  ]
}

While currentOrg is a valid query for the Studio API, it requires a selection of subfields. Which subfields you fetch is up to you. Here's an example with a few of the possible fields. To see all of the fields available, check the query reference.

Query

query {
  currentOrg {
    id
    name
    slug
    status
    createdAt
  }
}

Response

{
  "data": {
    "currentOrg": {
      "id": "3fd0011c-b6c2-4cc9-92ba-2e1474401fa4",
      "name": "Edge Press",
      "slug": null,
      "status": "ACTIVE",
      "createdAt": "2019-12-02T06:05:38.841319+00:00"
    }
  },
  "meta": {
    "graphqlQueryCost": 1
  }
}

The fields we added for id, name, etc. are not the only fields you could fetch. There are many more that you can explore using a GraphQL browser. Try exploring the schema (usually available in a button such as "Docs" or "Schema" in your browser).

GraphQL Types

What we've fetched so far are purely Scalar types. All fields that resolve to concrete data are Scalar types, and GraphQL by default has just a few:

Int: A signed 32‐bit integer.
Float: A signed double-precision floating-point value.
String: A UTF‐8 character sequence.
Boolean: true or false.
ID: A unique identifier string.

There are also a large number of custom Object types that respresent domain-specific knowledge. In the Studio API these are things like User, Playlist, Screen, and many more.

Overview

Get an API Token