> ## Documentation Index
> Fetch the complete documentation index at: https://docs.learningcommons.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting started

> Get started with the Knowledge Graph GraphQL API by learning the base URL, authentication requirements, and making your first request with code examples in cURL, Python, and JavaScript.

export const GatedCallout = ({children}) => <div className="eyebrow-callout not-prose rounded-xl border border-gray-200/80 p-5 dark:border-white/10" style={{
  marginBottom: "1rem",
  borderRadius: "4px"
}}>
    <div className="mb-3">
      <Badge color="orange" size="md" icon="lock">
        Gated
      </Badge>
    </div>
    <div className="callout-body text-[15px] leading-relaxed text-gray-700 dark:text-gray-300">{children}</div>
    <style>{`.callout-body a { text-decoration: underline; text-decoration-color: #178251; }`}</style>
  </div>;

export const EarlyAccessCallout = ({children}) => <div className="eyebrow-callout not-prose rounded-xl border border-gray-200/80 p-5 dark:border-white/10" style={{
  marginBottom: "1rem",
  borderRadius: "4px"
}}>
    <div className="mb-3">
      <Badge color="green" size="md" icon="flask">
        Early access
      </Badge>
    </div>
    <div className="callout-body text-[15px] leading-relaxed text-gray-700 dark:text-gray-300">{children}</div>
    <style>{`.callout-body a { text-decoration: underline; text-decoration-color: #178251; }`}</style>
  </div>;

<GatedCallout>
  Access to this resource is restricted and requires prior approval. In some cases, a license may also be required. Contact [support@learningcommons.org ↗](mailto:support@learningcommons.org) for information about access and eligibility.
</GatedCallout>

## What you'll need

* Base URL:
  ```text theme={null}
  POST https://cumtxmqb68.execute-api.us-west-2.amazonaws.com/staging/v1.0.0/graphql
  ```

* API key to include in the request headers: `x-api-key: YOUR_API_KEY`

  <Note>
    The Learning Commons team will securely share an API key for the GraphQL
    endpoint with you separately.
  </Note>

* For Python: [`gql`](https://github.com/graphql-python/gql) for better GraphQL support, schema validation, and error handling

  ```bash theme={null}
  pip install gql[requests]
  ```

## Query the data

Use [GraphQL](https://graphql.org/learn/) queries to fetch the Knowledge Graph data you're interested in.

For example, you can retrieve up to 5 courses with identifiers, names, and academic subjects using the queries below:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST \
    -H 'Content-Type: application/json' \
    -H 'x-api-key: YOUR_API_KEY' \
    -d '{"query":"{ courses(limit: 5) { identifier name academicSubject } }"}' \
    https://cumtxmqb68.execute-api.us-west-2.amazonaws.com/staging/v1.0.0/graphql
  ```

  ```python Python theme={null}
  import os
  from gql import Client, gql
  from gql.transport.requests import RequestsHTTPTransport

  # Setup client
  transport = RequestsHTTPTransport(
      url="https://cumtxmqb68.execute-api.us-west-2.amazonaws.com/staging/v1.0.0/graphql",
      headers={"x-api-key": os.getenv("API_KEY")},  # Your API key
      use_json=True,
  )

  client = Client(transport=transport, fetch_schema_from_transport=False)

  # Execute query
  query = gql("""
  {
    courses(limit: 5) {
      identifier
      name
      academicSubject
    }
  }
  """)

  result = client.execute(query)
  print(result)
  ```

  ```javascript JavaScript theme={null}
  const url =
    "https://cumtxmqb68.execute-api.us-west-2.amazonaws.com/staging/v1.0.0/graphql";
  const apiKey = process.env.API_KEY; // Your API key

  const query = `
  {
    courses(limit: 5) {
      identifier
      name
      academicSubject
    }
  }
  `;

  fetch(url, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-key": apiKey,
    },
    body: JSON.stringify({ query }),
  })
    .then((response) => response.json())
    .then((data) => console.log(data))
    .catch((error) => console.error("Error:", error));
  ```
</CodeGroup>

## Troubleshooting

### Query too complex

If your query times out or fails:

* Reduce the depth of nested relationships
* Implement pagination on nested connections
* Split complex queries into multiple simpler ones

### No results returned

If your query returns an empty response:

* Check filter conditions are correct
* Verify field names match the schema
* Use introspection queries to explore available fields

### Authentication errors

If your query fails authentication:

* Ensure your API key is valid and active
* Check that the `x-api-key` header is properly set

### Rate limiting

The API implements rate limiting to ensure fair usage:

* 2 requests per second with burst capacity up to 10 requests
* Exponential backoff when receiving rate limit errors (`HTTP 429: Too Many Requests`)

Reach out to [support@learningcommons.org](mailto:support@learningcommons.org) ↗ to request rate limit adjustments.

### Server errors

Large queries may cause `HTTP 502/504` errors:

* Reduce page size to fewer than 1000 items
* Retry the query

### Payload and timeout limits

The API has the following technical limitations:

* **Request timeout:** 30 sec
* **Request payload size:** 10 MB
* **Response payload size:** 6 MB
* **Query complexity:** Deeply nested queries may hit processing limits

To avoid limits:

* Use pagination for large result sets
* Limit field selection to only required data
* Avoid deeply nested queries (>5 levels)
* Break up complex queries or add filtering (e.g., grade level or subject)

### GraphQL errors

GraphQL errors are returned in the response body:

```text theme={null}
{
  "errors": [
    {
      "message": "Field 'invalidField' doesn't exist on type 'Lesson'",
      "locations": [{"line": 2, "column": 5}]
    }
  ]
}
```