API Discovery

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:

{
  "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

No URL Hardcoding

Follow links instead of constructing URLs manually.

Discoverable Actions

The API tells you what you can do next.

Future-Proof

URL changes won’t break your integration.

Self-Documenting

Links include titles explaining each action.

Pagination Example

List endpoints return pagination links:

{
  "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.

Common

health

analyses

prompts

Hypermedia-Driven API

Response Structure

Link Properties

Common Relationships

Benefits

No URL Hardcoding

Discoverable Actions

Future-Proof

Self-Documenting

​Hypermedia-Driven API

​Response Structure

​Link Properties

​Common Relationships

​Benefits

No URL Hardcoding

Discoverable Actions

Future-Proof

Self-Documenting

​Pagination Example

Hypermedia-Driven API

Response Structure

Link Properties

Common Relationships

Benefits

Pagination Example