# API Discovery
Source: https://docs.greetincs.com/common/api-discovery

Navigate the API using HATEOAS links

## Hypermedia-Driven API

The GreetIncs API implements HATEOAS (Hypermedia as the Engine of Application State). Every response includes a `links` array that tells you what actions are available and where related resources live.

### Response Structure

All responses follow this structure:

```json theme={null}
{
  "response_type": "AnalysisCreateResponse",
  "data": { ... },
  "links": [
    {
      "href": "/v1/analyses/analysis_01h45ytscbebyvny4gc8cr8ma2",
      "rel": "self",
      "method": "GET",
      "title": "Get Analysis"
    },
    {
      "href": "/v1/analyses/analysis_01h45ytscbebyvny4gc8cr8ma2/status",
      "rel": "status",
      "method": "GET",
      "title": "Check Status"
    },
    {
      "href": "/v1/analyses/analysis_01h45ytscbebyvny4gc8cr8ma2/results",
      "rel": "results",
      "method": "GET",
      "title": "Get Results"
    }
  ]
}
```

### Link Properties

| Property | Description                                                               |
| -------- | ------------------------------------------------------------------------- |
| `href`   | The URL path to the related resource                                      |
| `rel`    | The relationship type (e.g., `self`, `next`, `prev`, `status`, `results`) |
| `method` | The HTTP method to use                                                    |
| `title`  | Human-readable description of the action                                  |

### Common Relationships

| Relationship | Meaning                                |
| ------------ | -------------------------------------- |
| `self`       | The current resource                   |
| `next`       | Next page in paginated results         |
| `prev`       | Previous page in paginated results     |
| `status`     | Check the status of an async operation |
| `results`    | Retrieve completed results             |
| `related`    | Associated resources                   |

### Benefits

<CardGroup>
  <Card title="No URL Hardcoding" icon="link-slash">
    Follow links instead of constructing URLs manually.
  </Card>

  <Card title="Discoverable Actions" icon="compass">
    The API tells you what you can do next.
  </Card>

  <Card title="Future-Proof" icon="shield-check">
    URL changes won't break your integration.
  </Card>

  <Card title="Self-Documenting" icon="book">
    Links include titles explaining each action.
  </Card>
</CardGroup>

### Pagination Example

List endpoints return pagination links:

```json theme={null}
{
  "response_type": "AnalysisPaginatedListResponse",
  "data": {
    "data": [...],
    "total": 150,
    "page": 2,
    "page_size": 50
  },
  "links": {
    "self": { "href": "/v1/analyses/?page=2", "rel": "self", "method": "GET" },
    "prev": { "href": "/v1/analyses/?page=1", "rel": "prev", "method": "GET" },
    "next": { "href": "/v1/analyses/?page=3", "rel": "next", "method": "GET" },
    "total": 150
  }
}
```

Follow the `next` link to get the next page—no need to calculate offsets yourself.


# Authentication
Source: https://docs.greetincs.com/common/authentication

How to authenticate with the GreetIncs API

## API Key Authentication

All API requests (except the health check endpoint) require authentication via an API key.

### Getting an API Key

API keys are issued through your GreetIncs dashboard. Keys follow the format:

```
greetincs_...
```

### Using Your API Key

Include your API key in the `X-API-Key` header with every request:

```bash theme={null}
curl -X GET "https://api.greetincs.com/v1/analyses/" \
  -H "X-API-Key: greetincs_your_api_key"
```

### Security Best Practices

<Warning>
  Never expose your API key in client-side code, public repositories, or logs.
</Warning>

* Store API keys in environment variables or secrets managers
* Use different keys for development and production
* Rotate keys periodically
* Revoke compromised keys immediately

### Error Responses

| Status | Meaning                                              |
| ------ | ---------------------------------------------------- |
| 401    | Missing or invalid API key                           |
| 402    | Payment required - check your account status         |
| 403    | API key valid but lacks permission for this resource |