Skip to main content
API docs by Redocly

Gravy Connect API - Public (1.0)

Download OpenAPI specification:Download

Public API endpoints for Gravy Connect

account-info

Get paginated account info for a connection

Retrieve get paginated account info for a connection with pagination, filtering, and sorting support

path Parameters
connectionId
required
string

Connection ID

query Parameters
search
string

Search term for filtering account info

name
string

Filter by name

email
string

Filter by email

phone
string

Filter by phone

page
number
Default: 1

Page number (1-based)

limit
number
Default: 20

Items per page (1-100)

sortBy
string
Enum: "createdAt" "updatedAt" "title" "type"

Sort field

sortOrder
string
Enum: "asc" "desc"

Sort order

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    },
  • "timestamp": "2024-01-15T10:30:00.000Z",
  • "version": "v1"
}

balance

Get paginated balances for a connection

Retrieve get paginated balances for a connection with pagination, filtering, and sorting support

path Parameters
connectionId
required
string

Connection ID

query Parameters
search
string

Search term for filtering balances

type
string
Enum: "gift_card" "points" "rewards" "cash" "credit" "store_credit" "loyalty_points" "miles" "other"

Filter by balance type

currency
string

Filter by currency

isActive
boolean

Filter by active status

expiresFrom
string

Filter by expiration date (from)

expiresTo
string

Filter by expiration date (to)

amountMin
number

Filter by minimum amount

amountMax
number

Filter by maximum amount

page
number
Default: 1

Page number (1-based)

limit
number
Default: 20

Items per page (1-100)

sortBy
string
Enum: "createdAt" "updatedAt" "title" "type"

Sort field

sortOrder
string
Enum: "asc" "desc"

Sort order

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    },
  • "timestamp": "2024-01-15T10:30:00.000Z",
  • "version": "v1"
}

billing-statement

Get paginated billing statements for a connection

Retrieve get paginated billing statements for a connection with pagination, filtering, and sorting support

path Parameters
connectionId
required
string

Connection ID

query Parameters
page
number
Default: 1
Example: page=1

Page number (1-based)

limit
number [ 1 .. 100 ]
Default: 20
Example: limit=20

Items per page (1-100)

sortBy
string
Enum: "createdAt" "updatedAt" "title" "type"

Sort field

sortOrder
string
Enum: "asc" "desc"

Sort order

search
string

Search by external ID or vendor ID

status
string
Enum: "open" "paid" "past_due" "adjusted"

Filter by status

periodStart
string

Filter by period start date (YYYY-MM-DD)

periodEnd
string

Filter by period end date (YYYY-MM-DD)

amountDueMin
number

Filter by minimum amount due

amountDueMax
number

Filter by maximum amount due

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    },
  • "timestamp": "2024-01-15T10:30:00.000Z",
  • "version": "v1"
}

generic-history

Get paginated generic history for a connection

Retrieve get paginated generic history for a connection with pagination, filtering, and sorting support

path Parameters
connectionId
required
string

Connection ID

query Parameters
search
string

Search term for filtering history items

type
string

Filter by type

startDate
string

Filter by start date (ISO string)

endDate
string

Filter by end date (ISO string)

page
number
Default: 1

Page number (1-based)

limit
number
Default: 20

Items per page (1-100)

sortBy
string
Enum: "createdAt" "updatedAt" "title" "type"

Sort field

sortOrder
string
Enum: "asc" "desc"

Sort order

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    },
  • "timestamp": "2024-01-15T10:30:00.000Z",
  • "version": "v1"
}

loyalty

Get paginated loyalty for a connection

Retrieve get paginated loyalty for a connection with pagination, filtering, and sorting support

path Parameters
connectionId
required
string

Connection ID

query Parameters
search
string

Search term for filtering loyalty

loyaltyTier
string

Filter by loyalty tier

page
number
Default: 1

Page number (1-based)

limit
number
Default: 20

Items per page (1-100)

sortBy
string
Enum: "createdAt" "updatedAt" "title" "type"

Sort field

sortOrder
string
Enum: "asc" "desc"

Sort order

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    },
  • "timestamp": "2024-01-15T10:30:00.000Z",
  • "version": "v1"
}

payment-method

Get paginated payment method for a connection

Retrieve get paginated payment method for a connection with pagination, filtering, and sorting support

path Parameters
connectionId
required
string

Connection ID

query Parameters
page
number
Default: 1
Example: page=1

Page number (1-based)

limit
number [ 1 .. 100 ]
Default: 20
Example: limit=20

Items per page (1-100)

sortBy
string
Enum: "createdAt" "updatedAt" "title" "type"

Sort field

sortOrder
string
Enum: "asc" "desc"

Sort order

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    },
  • "timestamp": "2024-01-15T10:30:00.000Z",
  • "version": "v1"
}

reading-history

Get paginated reading history for a connection

Retrieve get paginated reading history for a connection with pagination, filtering, and sorting support

path Parameters
connectionId
required
string

Connection ID

query Parameters
page
number
Default: 1
Example: page=1

Page number (1-based)

limit
number [ 1 .. 100 ]
Default: 20
Example: limit=20

Items per page (1-100)

sortBy
string
Enum: "createdAt" "updatedAt" "title" "type"

Sort field

sortOrder
string
Enum: "asc" "desc"

Sort order

search
string
Example: search=Harry Potter

Search by title (case-insensitive)

author
string
Example: author=J.K. Rowling

Filter by author (case-insensitive)

read
boolean
Example: read=true

Filter by reading status

minProgress
number [ 0 .. 100 ]
Example: minProgress=50

Filter by minimum progress percentage

maxProgress
number [ 0 .. 100 ]
Example: maxProgress=100

Filter by maximum progress percentage

startDate
string
Example: startDate=2024-01-01T00:00:00.000Z

Filter by date range - start date (ISO string)

endDate
string
Example: endDate=2024-12-31T23:59:59.999Z

Filter by date range - end date (ISO string)

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    },
  • "timestamp": "2024-01-15T10:30:00.000Z",
  • "version": "v1"
}

trips

Get paginated trips for a connection

Retrieve get paginated trips for a connection with pagination, filtering, and sorting support

path Parameters
connectionId
required
string

Connection ID

query Parameters
search
string

Search term for filtering trips

type
string
Enum: "hotel" "flight" "rental_car" "train" "cruise" "package" "ride" "ground_transport" "wishlist" "other"

Filter by trip type

bookingStatus
string
Enum: "confirmed" "pending" "cancelled" "completed" "in_progress" "wishlist" "failed" "expired" "unknown"

Filter by booking status

provider
string

Filter by provider

locationCity
string

Filter by location city

locationCountryCode
string

Filter by location country code

checkInFrom
string

Filter by check-in date (from)

checkInTo
string

Filter by check-in date (to)

checkOutFrom
string

Filter by check-out date (from)

checkOutTo
string

Filter by check-out date (to)

amountMin
number

Filter by minimum amount

amountMax
number

Filter by maximum amount

currency
string

Filter by currency

page
number
Default: 1

Page number (1-based)

limit
number
Default: 20

Items per page (1-100)

sortBy
string
Enum: "createdAt" "updatedAt" "title" "type"

Sort field

sortOrder
string
Enum: "asc" "desc"

Sort order

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    },
  • "timestamp": "2024-01-15T10:30:00.000Z",
  • "version": "v1"
}

intent-token

Create intent token

header Parameters
x-passage-earn
required
string
Request Body schema: application/json
required
integrationId
required
string

The integration ID

products
required
Array of strings
Deprecated

The products to be requested

operations
required
Array of strings
Deprecated

The operations to be performed

userId
required
string

The client managed user ID

required
Array of objects (PromptDto)
Deprecated

AI Prompts to be used for the connection. Each prompt contains a name (key) and value (instruction) that will be used to customize the AI behavior for this connection.

sessionArgs
required
object
Deprecated

Additional arguments for the session

debug
required
boolean

Whether the intent token is for debug purposes

captureScreenshot
required
boolean

Whether to enable screenshot capture functionality

resources
required
object

Resources and operations to be performed. Each resource can have 'read' and/or 'write' operations with their respective arguments. Each operation can have an optional 'required' flag to indicate if the operation must succeed.

returnUrl
required
string

The URL the user will be redirected to after the connection is created. It will include the connectionId as a query parameter.

webhookUrl
required
string

Custom webhook URL for this connection. If provided, webhook notifications will be sent to this URL instead of the developer's default webhook URL.

Responses

Request samples

Content type
application/json
{
  • "integrationId": "audible",
  • "products": [
    ],
  • "operations": [
    ],
  • "userId": "123",
  • "prompts": [
    ],
  • "sessionArgs": {
    },
  • "debug": false,
  • "captureScreenshot": false,
  • "resources": {
    },
  • "returnUrl": "string",
  • "webhookUrl": "https://example.com/webhook"
}

Response samples

Content type
application/json
{}

connections

Get all connections for a developer

query Parameters
page
number
Default: 1
Example: page=1

Page number (1-based)

limit
number [ 1 .. 100 ]
Default: 20
Example: limit=20

Number of items per page

sortBy
string
Default: "createdAt"
Enum: "createdAt" "updatedAt"

Sort by field

sortOrder
string
Default: "desc"
Enum: "asc" "desc"

Sort order

status
string
Example: status=connected

Filter by status

integrationId
string
Example: integrationId=spotify

Filter by integration ID

userId
string
Example: userId=1234567890

Filter by user ID

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    },
  • "timestamp": "2024-01-15T10:30:00.000Z",
  • "version": "v1"
}

Get a connection by ID for a developer

path Parameters
connectionId
required
string

Connection ID

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "integrationId": "string",
  • "status": "pending",
  • "failureReason": "string",
  • "errorMessage": "string",
  • "errorDetails": { },
  • "connectionMetadata": { },
  • "resources": [
    ],
  • "userId": "user_1234567890",
  • "createdAt": "2024-01-15T10:30:00.000Z",
  • "updatedAt": "2024-01-15T10:30:00.000Z"
}

Delete a connection for a developer

path Parameters
id
required
string

Connection ID

Responses

integrations

Get all integrations

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get an integration by slug

path Parameters
slug
required
string

Integration slug

Responses

Response samples

Content type
application/json
{
  • "slug": "string",
  • "name": "string",
  • "type": "string",
  • "logoUrl": "string",
  • "url": "string",
  • "preAutomationSteps": [
    ],
  • "description": "string",
  • "active": true,
  • "version": "string",
  • "beta": true,
  • "resources": [
    ]
}

auth

OAuth 2.0 Client Credentials Token Endpoint

Exchange client credentials for an access token using OAuth 2.0 client credentials flow

Request Body schema: application/json
required
grant_type
required
string

The grant type

client_id
required
string

The client ID

client_secret
required
string

The client secret

scope
required
string

The scope

Responses

Request samples

Content type
application/json
{
  • "grant_type": "client_credentials",
  • "client_id": "123",
  • "client_secret": "123",
  • "scope": "read write"
}

Response samples

Content type
application/json
{
  • "access_token": "123",
  • "token_type": "Bearer",
  • "expires_in": 3600,
  • "scope": "read write"
}