Apps

Apps represent authenticated connections to external platforms like Shopify, Stripe, Google Ads, Meta Ads, and more. Each app stores credentials and can be used as a source (import data) or destination (export data).

List Apps

Retrieve all app connections for your account.


GET /api/v1/apps

Query Parameters

Parameter	Type	Description
`limit`	integer	Number of items to return (default: 20, max: 100)
`offset`	integer	Number of items to skip (default: 0)
`sort`	string	Sort field and order (e.g., `created_at:desc`)
`state`	string	Filter by state: `active`, `inactive`
`role`	string	Filter by role: `source`, `destination`
`app_type_id`	string	Filter by app type (e.g., `shopify`, `stripe`)

Example Request


curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://app.vendodata.com/api/v1/apps?state=active&limit=10"

Example Response


{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "accountId": "123e4567-e89b-12d3-a456-426614174000",
      "displayName": "My Shopify Store",
      "appTypeId": "shopify",
      "role": ["source"],
      "state": "active",
      "status": "completed",
      "isActive": true,
      "lastSyncAt": "2024-03-04T10:30:00Z",
      "consecutiveFailures": 0,
      "createdAt": "2024-01-15T08:00:00Z",
      "updatedAt": "2024-03-04T10:30:00Z"
    },
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "accountId": "123e4567-e89b-12d3-a456-426614174000",
      "displayName": "Google Ads - Main Account",
      "appTypeId": "google_ads",
      "role": ["source", "destination"],
      "state": "active",
      "status": "pending",
      "isActive": true,
      "lastSyncAt": null,
      "consecutiveFailures": 0,
      "createdAt": "2024-02-20T14:00:00Z",
      "updatedAt": "2024-02-20T14:00:00Z"
    }
  ],
  "meta": {
    "pagination": {
      "total": 2,
      "limit": 10,
      "offset": 0,
      "hasMore": false
    }
  }
}

Get App Details

Retrieve details for a specific app connection.


GET /api/v1/apps/{appId}

Path Parameters

Parameter	Type	Description
`appId`	string (UUID)	The app’s unique identifier

Example Request


curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://app.vendodata.com/api/v1/apps/550e8400-e29b-41d4-a716-446655440000

Example Response


{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "accountId": "123e4567-e89b-12d3-a456-426614174000",
    "displayName": "My Shopify Store",
    "appTypeId": "shopify",
    "role": ["source"],
    "state": "active",
    "status": "completed",
    "isActive": true,
    "credentials": {
      "shop_domain": "my-store.myshopify.com"
    },
    "lastSyncAt": "2024-03-04T10:30:00Z",
    "lastError": null,
    "consecutiveFailures": 0,
    "createdAt": "2024-01-15T08:00:00Z",
    "updatedAt": "2024-03-04T10:30:00Z"
  }
}

Create App

Create a new app connection.


POST /api/v1/apps

Request Body

Field	Type	Required	Description
`appTypeId`	string	Yes	The type of app (e.g., `shopify`, `stripe`)
`displayName`	string	Yes	Human-readable name for this connection
`credentials`	object	Yes	App-specific credentials

Credentials by App Type

Shopify


{
  "shop_domain": "my-store.myshopify.com",
  "access_token": "shpat_xxxxx"
}

Stripe


{
  "api_key": "sk_live_xxxxx"
}

Google Ads (OAuth-based apps require web UI setup)


{
  "customer_id": "123-456-7890",
  "refresh_token": "1//xxxxx"
}

Example Request


curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "appTypeId": "stripe",
    "displayName": "Production Stripe",
    "credentials": {
      "api_key": "sk_live_xxxxx"
    }
  }' \
  https://app.vendodata.com/api/v1/apps

Example Response


{
  "data": {
    "id": "770e8400-e29b-41d4-a716-446655440002",
    "accountId": "123e4567-e89b-12d3-a456-426614174000",
    "displayName": "Production Stripe",
    "appTypeId": "stripe",
    "role": ["source"],
    "state": "active",
    "status": "pending",
    "createdAt": "2024-03-04T15:00:00Z"
  }
}

Update App

Update an existing app connection.


PATCH /api/v1/apps/{appId}

Request Body

Field	Type	Description
`displayName`	string	Updated display name
`credentials`	object	Updated credentials

Example Request


curl -X PATCH \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"displayName": "Stripe - Live"}' \
  https://app.vendodata.com/api/v1/apps/770e8400-e29b-41d4-a716-446655440002

Delete App

Soft-delete an app connection. The app will be marked as deleted and no longer appear in listings.


DELETE /api/v1/apps/{appId}

Example Request


curl -X DELETE \
  -H "Authorization: Bearer YOUR_API_KEY" \
  https://app.vendodata.com/api/v1/apps/770e8400-e29b-41d4-a716-446655440002

Example Response


{
  "data": {
    "success": true,
    "message": "App deleted successfully"
  }
}

Pause App

Temporarily pause an app. Paused apps will not sync data.


POST /api/v1/apps/{appId}/pause

Example Request


curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  https://app.vendodata.com/api/v1/apps/550e8400-e29b-41d4-a716-446655440000/pause

Example Response


{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "state": "inactive",
    "status": "paused"
  }
}

Resume App

Resume a paused app.


POST /api/v1/apps/{appId}/resume

Example Request


curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  https://app.vendodata.com/api/v1/apps/550e8400-e29b-41d4-a716-446655440000/resume

Example Response


{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "state": "active",
    "status": "pending"
  }
}

App States and Statuses

States (User-Controlled)

State	Description
`active`	App is enabled and will sync
`inactive`	App is paused by user
`deleted`	App has been soft-deleted

Statuses (System-Controlled)

Status	Description
`pending`	Waiting to sync
`running`	Currently syncing
`completed`	Last sync completed successfully
`warning`	Completed with warnings
`errored`	Last sync failed
`paused`	User-initiated pause
`draft`	Incomplete setup