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

# Hologram REST API

> The Hologram HTTP API is a REST-style interface for managing Hologram devices, accounts, and cloud data. Using this API, you can activate SIMs, get your devices' approximate location, send SMS messages to your devices, update data usage limits, and much more.

## Base URL

```
https://dashboard.hologram.io/api/1
```

## Authentication

Hologram supports **HTTP Basic authentication** using API keys. Set the username to `apikey` and use your API key as the password.

### Using cURL

```bash theme={null}
curl --verbose GET \
  'https://dashboard.hologram.io/api/1/users/me' \
  -u apikey:YOUR_API_KEY
```

### Using authorization header

You can also base64 encode `apikey:YOUR_API_KEY` and include it in the Authorization header:

```bash theme={null}
curl --verbose GET \
  'https://dashboard.hologram.io/api/1/users/me' \
  --header "Authorization: Basic BASE64_ENCODED_CREDENTIALS"
```

## API access levels

* **Read Access**: Available to Editor roles and higher.
* **Write Access**: Varies by endpoint based on role access, generally limited to Admin and Manager roles.

Users without appropriate permissions will receive 403 errors for restricted operations.

## Requests

Request bodies can be provided in either JSON or form-urlencoded formats:

### JSON format (recommended)

```bash theme={null}
curl --request POST \
  --header "Content-Type: application/json" \
  --header "Authorization: Basic YOUR_ENCODED_CREDENTIALS" \
  --data '{"deviceid": 56668, "body": "Hello device!"}' \
  'https://dashboard.hologram.io/api/1/sms/incoming'
```

### Form-urlencoded format

```bash theme={null}
curl --request POST \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --header "Authorization: Basic YOUR_ENCODED_CREDENTIALS" \
  --data 'deviceid=56668&body=Hello%20device!' \
  'https://dashboard.hologram.io/api/1/sms/incoming'
```

## Responses

<Danger>
  **Important:** All Hologram dates and times are stored and displayed in **UTC**.
</Danger>

### Response format

All API responses are JSON objects that include the following fields.

<ResponseField name="success" type="boolean" required>
  Indicates whether the request was successful.
</ResponseField>

<ResponseField name="data" type="object or array">
  Contains the requested data or information about the operation performed. Only present when <code>success</code> is true.
</ResponseField>

<ResponseField name="error" type="string">
  Information about why the request failed. Only present when <code>success</code> is false.
</ResponseField>

### Limited responses

Most GET responses will also include the following fields if a limit is included as part of the query string:

<Expandable title="fields">
  <ResponseField name="limit" type="number">
    The query limit. Some endpoints have this value built in and others often have a maximum value.
  </ResponseField>

  <ResponseField name="size" type="number">
    The number of values returned by the query.
  </ResponseField>

  <ResponseField name="continues" type="boolean, optional">
    Only returned if there are more values than were returned in the response.
  </ResponseField>

  <ResponseField name="links" type="array">
    Contains information related to the query performed.
  </ResponseField>

  <ResponseField name="path" type="string">
    The API endpoint path.
  </ResponseField>

  <ResponseField name="base" type="string">
    API base URL.
  </ResponseField>

  <ResponseField name="next" type="string">
    URL with query string to get the next results.
  </ResponseField>
</Expandable>

## Rate limiting

In order to provide a consistent quality of service to all of our customers, we enforce a rate limit on all API requests. If you exceed the rate limit you will receive a HTTP 429 response with a JSON response body like this:

```json theme={null}
{
  "success": false,
  "error": "API rate limit exceeded"
}
```

If you receive this response, you should refrain from making requests for 5-10 seconds and then retry the request.

## Generating an API key

Find your account API key in your [dashboard](https://dashboard.hologram.io/settings/api) under the **Settings** section in the main menu, then opening the **API** page.

Your API can be used to access all organizations you are a member of.

<Warning>
  **Caution:** **Keep your API key secure** and never store it in publicly accessible places like GitHub repositories.
</Warning>

## Organization IDs

Many endpoints accept an `orgid` parameter to filter for devices within a specific organization. Learn how to find your organization's ID in [this guide](/dashboard/orgs-and-users/organization-overview).

## Support

For API support, questions, or additional assistance, please [contact our support team](/guides/get-started/contact-support).