# REST API Documentation

Integrate Appy with external applications using our RESTful API. Manage apps, builds, and notifications programmatically.

#### On this page

- Authentication
- Creating API Keys
- Apps API
- Builds API
- Notifications API
- Account API

Note: API access requires a subscription plan with the "can_use_api" feature enabled. Check your plan features or contact your administrator.

## Authentication

Appy uses Laravel Sanctum for API authentication. All API requests must include a valid API token in the Authorization header.

### Base URL

    https://yourdomain.com/api/v1

### Authentication Header

Include your API token in all requests:

    Authorization: Bearer YOUR_API_TOKEN

### Response Format

All API responses are returned in JSON format:

    {
        "success": true,
        "data": { /* response data */ },
        "message": "Success message"
    }

### Error Responses

Errors return appropriate HTTP status codes:

    {
        "success": false,
        "message": "Error message",
        "errors": { /* validation errors if applicable */ }
    }

Status Code | Meaning
--- | ---
`200` | Success
`201` | Created
`400` | Bad Request
`401` | Unauthorized
`403` | Forbidden (API access not enabled)
`404` | Not Found
`422` | Validation Error
`429` | Too Many Requests (rate limit exceeded)
`500` | Internal Server Error

### Rate Limiting

API requests are rate-limited to ensure fair usage and platform stability:

Endpoint Type | Limit | Window
--- | --- | ---
Standard API endpoints | 60 requests | Per minute
AI Chat streaming | 30 requests | Per minute

When you exceed the rate limit, the API returns a `429 Too Many Requests` response. The response headers include:

- `X-RateLimit-Limit`: Maximum requests allowed
- `X-RateLimit-Remaining`: Requests remaining in current window
- `Retry-After`: Seconds until the rate limit resets

## Creating API Keys

Generate API tokens from your user account to authenticate API requests.

1

#### Navigate to API Keys

Log in and go to User > API Keys.

2

#### Create New Token

Click Create API Key and enter a name for your token (e.g., "App Integration").

3

#### Copy Your Token

Your token will be displayed once. Copy it immediately - you won't be able to see it again.

Security: Keep your API tokens secure. Never share them publicly or commit them to version control. If a token is compromised, delete it immediately.

## Apps API

Manage your apps programmatically.

### List All Apps

Retrieve a list of all your apps.

    GET /api/v1/apps

#### Example Request

    curl -X GET https://yourdomain.com/api/v1/apps \
      -H "Authorization: Bearer YOUR_API_TOKEN" \
      -H "Accept: application/json"

#### Example Response

    {
        "success": true,
        "data": [
            {
                "id": 1,
                "name": "My E-commerce App",
                "platform": "androidwebview",
                "created_at": "2024-01-15T10:30:00.000000Z",
                "updated_at": "2024-01-20T14:22:00.000000Z"
            }
        ]
    }

### Get Single App

Retrieve details of a specific app.

    GET /api/v1/apps/{app_id}

#### Example Request

    curl -X GET https://yourdomain.com/api/v1/apps/1 \
      -H "Authorization: Bearer YOUR_API_TOKEN" \
      -H "Accept: application/json"

### Create New App

Create a new app.

    POST /api/v1/apps

#### Request Parameters

Parameter | Type | Required | Description
--- | --- | --- | ---
`name` | string | Yes | App name
`platform` | string | Yes | Platform type (androidwebview)
`url` | string | Yes | Website URL
`package_name` | string | Yes | Unique package identifier

#### Example Request

    curl -X POST https://yourdomain.com/api/v1/apps \
      -H "Authorization: Bearer YOUR_API_TOKEN" \
      -H "Content-Type: application/json" \
      -H "Accept: application/json" \
      -d '{
        "name": "My Shop App",
        "platform": "androidwebview",
        "url": "https://myshop.com",
        "package_name": "com.myshop.app"
      }'

### Update App

Update an existing app's details.

    PUT /api/v1/apps/{app_id}

### Delete App

Delete an app permanently.

    DELETE /api/v1/apps/{app_id}

## Builds API

Manage app builds and download compiled APKs.

### List App Builds

Get all builds for a specific app.

    GET /api/v1/apps/{app_id}/builds

#### Example Response

    {
        "success": true,
        "data": [
            {
                "id": 1,
                "app_id": 1,
                "platform": "androidwebview",
                "build_type": "release",
                "build_format": "apk",
                "version_name": "1.0.0",
                "version_code": 1,
                "status": "completed",
                "artifact_size": 5242880,
                "build_duration": 245,
                "created_at": "2024-01-20T10:00:00.000000Z",
                "completed_at": "2024-01-20T10:04:05.000000Z"
            }
        ]
    }

### Get Build Details

Retrieve details of a specific build.

    GET /api/v1/builds/{build_id}

### Trigger New Build

Start a new app build.

    POST /api/v1/apps/{app_id}/builds

#### Request Parameters

Parameter | Type | Required | Description
--- | --- | --- | ---
`build_type` | string | Yes | debug or release
`build_format` | string | Yes | apk or aab
`keystore_id` | integer | No | Keystore ID (required for release)

#### Example Request

    curl -X POST https://yourdomain.com/api/v1/apps/1/builds \
      -H "Authorization: Bearer YOUR_API_TOKEN" \
      -H "Content-Type: application/json" \
      -H "Accept: application/json" \
      -d '{
        "build_type": "release",
        "build_format": "apk",
        "keystore_id": 1
      }'

### Get Download URL

Get a signed URL to download a completed build.

    GET /api/v1/builds/{build_id}/download

#### Example Response

    {
        "success": true,
        "data": {
            "download_url": "https://yourdomain.com/builds/1/download?signature=...",
            "expires_at": "2024-01-25T10:00:00.000000Z"
        }
    }

### Get Build Logs

Retrieve build logs for troubleshooting.

    GET /api/v1/builds/{build_id}/logs

## Notifications API

Send push notifications to app users.

### List Notifications

Get all notifications for an app.

    GET /api/v1/apps/{app_id}/notifications

### Send Notification

Send a push notification to all app users.

    POST /api/v1/apps/{app_id}/notifications

#### Request Parameters

Parameter | Type | Required | Description
--- | --- | --- | ---
`title` | string | Yes | Notification title
`body` | string | Yes | Notification message
`image_url` | string | No | Image URL
`scheduled_at` | datetime | No | Schedule for later

#### Example Request

    curl -X POST https://yourdomain.com/api/v1/apps/1/notifications \
      -H "Authorization: Bearer YOUR_API_TOKEN" \
      -H "Content-Type: application/json" \
      -H "Accept: application/json" \
      -d '{
        "title": "New Sale!",
        "body": "Get 50% off all items today only!",
        "image_url": "https://example.com/sale-banner.jpg"
      }'

### Get Notification Details

Retrieve details of a sent notification.

    GET /api/v1/notifications/{notification_id}

### Cancel Scheduled Notification

Cancel a scheduled notification before it's sent.

    DELETE /api/v1/notifications/{notification_id}

## Account API

Retrieve information about your account, subscription, and usage.

### Get Account Information

Retrieve your account details.

    GET /api/v1/account

#### Example Response

    {
        "success": true,
        "data": {
            "id": 1,
            "name": "John Doe",
            "email": "john@example.com",
            "role": "user",
            "status": "active",
            "build_credits": 50,
            "created_at": "2024-01-01T00:00:00.000000Z"
        }
    }

### Get Subscription Details

View your current subscription plan.

    GET /api/v1/account/subscription

#### Example Response

    {
        "success": true,
        "data": {
            "plan_name": "Pro",
            "status": "active",
            "amount": 29.99,
            "currency": "USD",
            "renewal_at": "2024-02-01T00:00:00.000000Z",
            "features": {
                "monthly_build_credits": 100,
                "can_use_custom_code": true,
                "can_use_appetize": true,
                "can_use_api": true
            }
        }
    }

### Get Usage Statistics

View your usage statistics for the current billing period.

    GET /api/v1/account/usage

#### Example Response

    {
        "success": true,
        "data": {
            "builds_used": 15,
            "builds_remaining": 85,
            "appetize_minutes_used": 45,
            "appetize_minutes_remaining": 255,
            "billing_period_start": "2024-01-01T00:00:00.000000Z",
            "billing_period_end": "2024-02-01T00:00:00.000000Z"
        }
    }

Full API Documentation: Visit `/docs/api` on your Appy installation for interactive API documentation with live request testing.

© 2026 Titan Systems. All Rights Reserved.