> ## Documentation Index
> Fetch the complete documentation index at: https://apidocs.royalti.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick Start Guide

> Get started with the Royalti.io API in just a few minutes

This guide will get you up and running with the Royalti.io API quickly. You'll learn how to authenticate, make your first API call, and explore core functionality.

## Prerequisites

Before you begin, you'll need:

* A Royalti.io account ([sign up here](https://app.royalti.io/register))
* API access credentials
* A tool to make HTTP requests (cURL, Postman, or your preferred programming language)

## Security Requirements

<Warning>
  **Important Security Notes:**

  * All API requests must use HTTPS
  * Never connect via unencrypted HTTP as this exposes your access token
  * Always verify SSL certificates - stop operations if certificate validation fails
  * Access tokens use industry-standard cryptographic algorithms
  * Store access tokens securely and never share with unauthorized parties
</Warning>

We support TLSv1.2 and later versions. Ensure your client supports modern encryption standards.

## Step 1: Get Your Access Token

<Steps>
  <Step title="Login to get refresh token">
    Send your credentials to the login endpoint:

    ```bash cURL theme={null}
    curl -X POST "https://api.royalti.io/auth/login" \
      -H "Content-Type: application/json" \
      -d '{
        "email": "your@email.com",
        "password": "your_password"
      }'
    ```

    This returns a `refresh_token` and list of your workspaces.
  </Step>

  <Step title="Exchange refresh token for access token">
    Use the refresh token to get an access token for your workspace:

    ```bash cURL theme={null}
    curl -X GET "https://api.royalti.io/auth/authtoken?currentWorkspace=WORKSPACE_ID" \
      -H "Authorization: Bearer YOUR_REFRESH_TOKEN"
    ```

    This returns an `access_token` that you'll use for all subsequent API calls.
  </Step>

  <Step title="Use the access token">
    Include the access token in all API requests:

    ```bash theme={null}
    Authorization: Bearer YOUR_ACCESS_TOKEN
    ```
  </Step>
</Steps>

<Note>
  Access tokens expire after 6 hours. Refresh tokens expire after 1 day. See the [Authentication guide](/introduction/authentication) for token lifecycle management.
</Note>

## Step 2: Make Your First API Call

Let's retrieve your user information:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.royalti.io/user" \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
    -H "Content-Type: application/json"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.royalti.io/user', {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
      'Content-Type': 'application/json'
    }
  });

  const userData = await response.json();
  console.log(userData);
  ```

  ```python Python theme={null}
  import requests

  headers = {
      'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
      'Content-Type': 'application/json'
  }

  response = requests.get('https://api.royalti.io/user', headers=headers)
  user_data = response.json()
  print(user_data)
  ```
</CodeGroup>

## Step 3: Common Operations

### Create a New Artist

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.royalti.io/artist/" \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "artistName": "Sample Artist",
      "signDate": "2024-01-21",
      "label": "Sample Records",
      "users": ["user-id-1", "user-id-2"],
      "split": [
        {"user": "user-id-1", "share": 60},
        {"user": "user-id-2", "share": 40}
      ]
    }'
  ```

  ```javascript JavaScript theme={null}
  const newArtist = await fetch('https://api.royalti.io/artist/', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      artistName: 'Sample Artist',
      signDate: '2024-01-21',
      label: 'Sample Records',
      users: ['user-id-1', 'user-id-2'],
      split: [
        { user: 'user-id-1', share: 60 },
        { user: 'user-id-2', share: 40 }
      ]
    })
  }).then(res => res.json());
  ```
</CodeGroup>

### Query Artists with Filters

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.royalti.io/artist?q=john&page=1&size=20&order=asc&sort=artistName&statistics=true" \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
  ```

  ```javascript JavaScript theme={null}
  const params = new URLSearchParams({
    q: 'john',
    page: '1',
    size: '20',
    order: 'asc',
    sort: 'artistName',
    statistics: 'true'
  });

  const artists = await fetch(`https://api.royalti.io/artist?${params}`, {
    headers: { 'Authorization': 'Bearer YOUR_ACCESS_TOKEN' }
  }).then(res => res.json());
  ```
</CodeGroup>

## Pagination, Sorting & Filtering

Most endpoints support these query parameters:

| Parameter    | Type    | Description                          | Default     |
| ------------ | ------- | ------------------------------------ | ----------- |
| `q`          | string  | Global search across multiple fields | None        |
| `page`       | number  | Page number for pagination           | 1           |
| `size`       | number  | Items per page                       | 10          |
| `order`      | string  | Sort order: 'asc' or 'desc'          | 'desc'      |
| `sort`       | string  | Field to sort by                     | 'updatedAt' |
| `attributes` | string  | Comma-separated fields to return     | All         |
| `statistics` | boolean | Include statistical data             | false       |

### Endpoint-Specific Filters

**Artists:**

* `user` - Filter by user ID(s), comma-separated
* `catalog` - Filter by catalog

**Assets:**

* `artist` - Filter by artist ID(s), comma-separated
* `type` - Filter by asset type
* `splits` - Include splits information

**Products:**

* `artist` - Filter by artist ID(s), comma-separated
* `type` - Filter by product type
* `splits` - Include splits information

## Response Format

All API responses follow this structure:

```json theme={null}
{
  "success": true,
  "data": {
    // Response data here
  },
  "total": 150,
  "page": 1,
  "size": 10
}
```

## Error Handling

The API uses standard HTTP status codes:

| Status Code | Description                                            |
| ----------- | ------------------------------------------------------ |
| **200**     | Success                                                |
| **400**     | Bad Request - invalid parameters or validation failure |
| **401**     | Unauthorized - invalid or expired token                |
| **404**     | Not Found - endpoint or entity doesn't exist           |
| **500**     | Internal Server Error                                  |

### Error Response Format

```json theme={null}
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input data",
    "details": ["Required field missing"]
  }
}
```

## Best Practices

### Performance Optimization

* Use the `attributes` parameter to limit response payload size
* Implement proper pagination for large datasets
* Cache responses where appropriate
* Use `statistics=false` unless statistical data is needed

### Error Handling

* Always check HTTP status codes
* Implement retry logic for 5xx errors
* Validate input data before sending requests
* Handle rate limiting gracefully

### Security

* Never expose access tokens in client-side code
* Use HTTPS for all requests
* Validate SSL certificates
* Rotate access tokens regularly

## Next Steps

Now that you've made your first API calls, explore:

* **[Authentication Reference](/introduction/authentication)** - Complete guide to all authentication methods
* **[API Reference](/api-reference)** - Comprehensive endpoint documentation
* **Artist Management** - Deep dive into artist and catalog management
* **Payment Processing** - Handle financial transactions and distributions

## Support

Need help? We're here for you:

* Full API Documentation
* [Support Center](https://support.royalti.io)
* [API Status Page](https://status.royalti.io)