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

# Stemfard REST API: base URL, auth, and request format

> Complete reference for the Stemfard mathematics REST API — base URL, authentication, request format, response structure, and all available endpoint groups.

The Stemfard API is a JSON-based REST API that gives you programmatic access to intelligent mathematics computations for STEM education. Every request targets a specific mathematical operation, and every response returns structured results that can include step-by-step explanations, background theory, and learning pathway links. You send a `POST` request with a JSON body, and you receive a JSON response.

## Base URL

All API requests are made to:

```
https://api.stemfard.com
```

The current API version is **v1**. All endpoint paths begin with `/api/v1/`.

## Authentication

You authenticate by including your API key in the `Authorization` header of every request.

```http theme={null}
Authorization: Bearer <your-api-key>
```

<Warning>
  Keep your API key secret. Do not expose it in client-side code or public repositories. If your key is compromised, rotate it immediately from your account dashboard.
</Warning>

## Request format

All endpoints accept `POST` requests with a `Content-Type: application/json` body. There are no query parameters — all inputs are passed in the request body as a JSON object.

```http theme={null}
POST /api/v1/mathematics/linear-algebra/matrix-operations/matrix-arithmetic/add
Content-Type: application/json
Authorization: Bearer <your-api-key>
```

## Response format

Responses are always JSON objects. A successful response returns HTTP `200` with a result object whose structure depends on the endpoint and the `api_level` you request. See the [errors reference](/api-reference/errors) for non-200 status codes.

## Minimal complete example

The following example adds two matrices and returns a detailed response with steps.

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.stemfard.com/api/v1/mathematics/linear-algebra/matrix-operations/matrix-arithmetic/add \
    --header 'Authorization: Bearer <your-api-key>' \
    --header 'Content-Type: application/json' \
    --data '{
      "a": [[1, 2], [3, 4]],
      "b": [[5, 6], [7, 8]],
      "result_name": "sum",
      "api_level": "standard"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.stemfard.com/api/v1/mathematics/linear-algebra/matrix-operations/matrix-arithmetic/add',
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer <your-api-key>',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        a: [[1, 2], [3, 4]],
        b: [[5, 6], [7, 8]],
        result_name: 'sum',
        api_level: 'standard',
      }),
    }
  );
  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.stemfard.com/api/v1/mathematics/linear-algebra/matrix-operations/matrix-arithmetic/add',
      headers={
          'Authorization': 'Bearer <your-api-key>',
          'Content-Type': 'application/json',
      },
      json={
          'a': [[1, 2], [3, 4]],
          'b': [[5, 6], [7, 8]],
          'result_name': 'sum',
          'api_level': 'standard',
      },
  )
  data = response.json()
  ```
</CodeGroup>

## Common request parameters

Every math endpoint accepts the following shared parameters in the request body, in addition to any operation-specific fields.

<ParamField body="result_name" type="string" default="ans">
  The name assigned to the computed result in the response object.
</ParamField>

<ParamField body="api_level" type="string" default="detailed">
  Controls response verbosity. Accepted values: `"lite"`, `"standard"`, `"detailed"`.
</ParamField>

<ParamField body="steps_bg" type="boolean" default="true">
  When `true`, includes background theory alongside each solution step.
</ParamField>

<ParamField body="steps_output_formats" type="string[]" default="[&#x22;&#x22;]">
  Format for rendered step content. Accepted values: `"html"`, `"latex"`, `"speech"`. Pass an empty string for plain text.
</ParamField>

<ParamField body="decimals" type="integer | null" default="null">
  Number of decimal places to round results to. Pass `null` to return full precision.
</ParamField>

<ParamField body="apply_decimals_in_steps" type="boolean" default="false">
  When `true`, applies `decimals` rounding to intermediate step values as well as the final result.
</ParamField>

<ParamField body="request_params" type="boolean" default="true">
  When `true`, includes a normalized copy of the request parameters in the response.
</ParamField>

<ParamField body="learning_pathways" type="boolean" default="true">
  When `true`, includes links to curated learning resources relevant to the operation.
</ParamField>

<ParamField body="related" type="boolean" default="true">
  When `true`, includes links to related Stemfard API endpoints in the response.
</ParamField>

<ParamField body="properties" type="boolean" default="true">
  When `true`, includes a description of the result object's properties in the response.
</ParamField>

<Note>
  The `api_level` parameter is the fastest way to control response size. Use `"lite"` when you only need the computed result and want to minimize payload size. Use `"standard"` for results with steps but without background theory. Use `"detailed"` (the default) for the richest response, including theory, learning pathways, and related endpoint links — ideal for educational interfaces.
</Note>

## Endpoint groups

The API is organized into endpoint groups by mathematical domain. Each group contains a combined endpoint (which accepts a `type` or `operation` parameter to select the specific computation) and individual focused endpoints for each operation.

| Group                 | Description                                                                                                    | Reference                                                            |
| --------------------- | -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| **Matrix arithmetic** | Add, subtract, multiply, divide, and raise matrices element-wise, plus standard matrix multiplication          | [matrix-arithmetic](/api-reference/linear-algebra/matrix-arithmetic) |
| **Matrix dimensions** | Query the number of rows, number of columns, or full shape of a matrix                                         | [matrix-dimensions](/api-reference/linear-algebra/matrix-dimensions) |
| **Matrix statistics** | Compute min, max, sum, mean, median, variance, and standard deviation across rows, columns, or the full matrix | [matrix-statistics](/api-reference/linear-algebra/matrix-statistics) |

## Error handling

When a request fails, the API returns a non-200 HTTP status code with a JSON error body. See the [errors reference](/api-reference/errors) for the full list of status codes and the validation error response schema.