# Getting Started

## Authentication

All calls to the Firmhouse GraphQL API require a valid `X-Project-Access-Token` HTTP header to be passed in every request. You can generate a Project Access Token by going to the **Settings > Integrations** page in your Firmhouse project as a project manager.

### Access Token Types

Each Project Access Token has a specific access type. The access type controls what the token can do (or cannot do) and which data is accessible via the token.

There a currently two access types: **write** and **storefront**. In the near future we will also introduce a **read** type. Read below on the details per access type.

#### **Write**

The write access type gives you full API access to all data. Treat this as an administrative secret that you should not expose to the public. This token can read and modify all data in your project. Always securely embed this token into your application and never expose this token to regular users or the public.

#### **Storefront**

The storefront access type is meant for building Headless applications or storefronts without needing a server-side component in your app. For example in your frontend React application or Apollo JS client. It is safe to expose this token to the public as part of your runtime codebase.

A storefront token will only give limited access to available products and plans. And it allows you to build a cart and initiate a subscription checkout and payment flow. This token does not give you access to subscription data after the subscription has signed up.

## Making calls

The API is exposed on the following endpoint:

```
POST https://portal.firmhouse.com/graphql
```

All calls towards our API should be made with a HTTP `POST`. Your HTTP `POST` should include a valid `X-Project-Access-Token` HTTP header as explained under Authentication.

Certain queries and mutations also need a `X-Subscription-Token` HTTP header to be present, alongside the `X-Project-Access-Token`. This is usually the case when a query or mutation accesses data of an individual subscription.

Calls can be made via standard server-to-server HTTP communication, but also by using Fetch from your customer's browser if you're building a frontend or headless experience without server-side component.

## Clients and libraries

There are several ways and clients that can be used to interact with the API. For example:

* Use a tool such as [GraphiQL](https://github.com/graphql/graphiql) or [Insomnia](https://insomnia.rest/products/insomnia) to interactively explore the API and its documentation.
* Use cURL to manually make calls from the command-line.
* Use the [GraphQL Ruby Client](https://github.com/github/graphql-client) to make calls from a Ruby on Rails app.
* Use [Apollo](https://www.apollographql.com/) when using React, Vue, or Next.js.

## Query Complexity

Every call to our API has a calculated query complexity. In the near future we will be rejecting queries that exceed a total complexity of **1000** for a single query.

New projects already have this limit applied. Existing API consumers will be notified of this change and will get the time to update their queries.

### How is complexity calculated?

Take the following example query, its total complexity is 27. The complexity is calculated based on the maximum possible value. In this example "collectionCases" could be less then 10 pages but its attributes are still multiplied by 10.

```gql
query {
  getSubscription(token: "token") {                  # +1
    token                                            # +1
    collectionCases(first: 10) {                     # +1
      nodes {                                        # +1
        id                                           # +10 (+1, multiplied by `first:` above)
        caseNumber                                   # +10 (+1, multiplied by `first:` above)
      }
      pageInfo {                                     # +1
        endCursor                                    # +1
      }
      totalCount                                     # +1
    }
  }
}
```

These are the defaults but it could be that certain fields take more resources to compute. We might increase the complexity manually for such fields.

The response of every query includes information about the requested complexity found in the path: "extensions.complexity.requestedQueryComplexity".

```json
{
  "data": {
    "getSubscription": {
      "token": "token",
      "collectionCases": {
        "nodes": [...],
        "pageInfo": {
          "endCursor": "..."
        },
        "totalCount": 1
      }
    }
  },
  "extensions": {
    "complexity": {
      "requestedQueryComplexity": 27
    }
  }
}
```

Take a look at the [pagination](/graphql-api/pagination.md) documentation for more information about how to paginate over large result sets and optimize your queries.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.firmhouse.com/graphql-api/getting-started.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.