# Quick Start

Get started with the GoSmarter API in minutes. This guide will walk you through authentication and making your first API call.

## Prerequisites

Before you begin, you'll need:

- **API Credentials** - Contact your administrator to get OAuth 2.0 client credentials
- **HTTP Client** - Use curl, Postman, or any HTTP library

## Step 1: Get an Access Token

The GoSmarter API uses OAuth 2.0 client credentials flow for authentication.

### Request

```bash
curl --request POST \
  --url 'https://YOUR_TENANT.ciamlogin.com/YOUR_TENANT/oauth2/v2.0/token' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data grant_type=client_credentials \
  --data client_id=YOUR_CLIENT_ID \
  --data client_secret=YOUR_CLIENT_SECRET \
  --data scope=api://YOUR_API_ID/access_as_user
```

### Response

```json
{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
  "token_type": "Bearer",
  "expires_in": 3599
}
```

:::tip

Save the `access_token` - you'll use it in the next steps. Tokens expire after about 1 hour.

:::

## Step 2: Make Your First API Call

Let's check the API health to verify everything is working:

```bash
curl --request GET \
  --url 'https://YOUR_GATEWAY_URL.zuplo.app/api/health' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

### Response

```json
{
  "status": "healthy",
  "timestamp": "2025-12-11T14:30:00Z"
}
```

:::tip{title="Success!"}

You've made your first API call.

:::

## Step 3: Try a Data Endpoint

Now let's fetch some real data. Here's how to check user synchronization status:

```bash
curl --request POST \
  --url 'https://YOUR_GATEWAY_URL.zuplo.app/api/CheckUserSync' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "userId": "user-uuid-here"
  }'
```

## Next Steps

- **[Authentication Guide](/docs/authentication)** - Learn more about OAuth 2.0 and token management
- **[API Reference](/api)** - Explore all available endpoints
- **[MCP Integration](/docs/mcp-integration)** - Connect AI agents to the API

## Common Operations

### List Operations

Most resources support listing with pagination:

```bash
curl --request GET \
  --url 'https://YOUR_GATEWAY_URL.zuplo.app/api/resource?page=1&limit=20' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

### Create Operations

Create new resources using POST:

```bash
curl --request POST \
  --url 'https://YOUR_GATEWAY_URL.zuplo.app/api/resource' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"field": "value"}'
```

### Update Operations

Update existing resources using PUT:

```bash
curl --request PUT \
  --url 'https://YOUR_GATEWAY_URL.zuplo.app/api/resource/ID' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"field": "new_value"}'
```

## Error Handling

The API uses standard HTTP status codes:

- `200 OK` - Request succeeded
- `400 Bad Request` - Invalid request data
- `401 Unauthorized` - Missing or invalid authentication
- `404 Not Found` - Resource doesn't exist
- `429 Too Many Requests` - Rate limit exceeded
- `500 Internal Server Error` - Server error

**Error Response Format:**

```json
{
  "error": {
    "code": "invalid_request",
    "message": "The request is missing a required parameter",
    "details": {
      "field": "userId",
      "reason": "required"
    }
  }
}
```

## Rate Limits

- **Default**: 1000 requests per hour per client
- **Burst**: Up to 50 requests per minute

:::info

Rate limit headers are included in every response:

- `X-RateLimit-Limit` - Total requests allowed
- `X-RateLimit-Remaining` - Requests remaining
- `X-RateLimit-Reset` - Time when limit resets (Unix timestamp)

:::

## Need Help?

- Check the [API Reference](/api) for detailed endpoint documentation
- Review the [Authentication Guide](/docs/authentication) for auth troubleshooting
- Contact support at support@gosmarter.ai