# MOGU Public API Documentation

Welcome to the MOGU Public API documentation. This API allows you to programmatically manage trips and catalogs for your travel business.

## Getting Started

### Authentication

All API endpoints require authentication using API Keys.

Include your API Key in the `Authorization` header of every request:


```
Authorization: Bearer YOUR_API_KEY
```

### Base URL

- **Production**: `https://trips.api.moguplatform.com`


## Quick Start

### 1. Obtain an API Key

To access the API, you'll need to generate an API Key from your MOGU account:

1. Log in to your MOGU account
2. Navigate to the **Integrations** tab in your account settings
3. Generate a new API Key


The API Key will start with `ak_` and will include the necessary permissions based on your account role.

**Learn how to generate an API Key**: For step-by-step instructions, see our [How to generate an API Key guide](https://help.moguplatform.com/en/articles/12868814-how-to-generate-an-api-key).

### 2. Make Your First Request

Here's a simple example to list your trips:


```bash
curl -X GET https://trips.api.moguplatform.com/trips \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

## Core Concepts

### Trips

Trips are the main entities in the MOGU platform. A trip represents a travel itinerary with all its details, configurations, and associated travelers.

**Key operations:**

- Create and manage trips
- Configure trip settings and branding
- Manage trip visibility (public/private)
- Track trip visualizations


### Catalogs

Catalogs are collections of trips that can be organized and shared. They allow you to group related trips for easier management and presentation.

**Key operations:**

- Create and organize catalogs
- Add/remove trips from catalogs
- Make catalogs publicly accessible
- Filter and search catalog trips


## API Features

### Pagination

List endpoints support pagination to handle large datasets efficiently:


```bash
GET /trips?page=1&pageSize=20
```

**Parameters:**

- `page`: Page number (starts at 1)
- `pageSize`: Number of items per page (default: 20, max: 100)


**Response format:**


```json
{
  "data": [...],
  "page": 1,
  "pageSize": 20,
  "totalCount": 150,
  "totalPages": 8
}
```

### Filtering

Apply filters to narrow down results using JSON syntax:


```bash
GET /trips?filters=[{"field":"duration","operator":"gte","value":5}]
```

**Supported operators:**

- `eq`: Equal to
- `neq`: Not equal to
- `gt`: Greater than
- `gte`: Greater than or equal to
- `lt`: Less than
- `lte`: Less than or equal to
- `in`: In array
- `contains`: Contains value


### Searching

Search across multiple fields using JSON syntax:


```bash
GET /trips?search={"fields":["title","code"],"term":"Paris"}
```

### Sorting

Sort results by any field:


```bash
GET /trips?orderBy={"field":"createdAt","direction":"desc"}
```

**Directions:**

- `asc`: Ascending order
- `desc`: Descending order


## Error Handling

The API uses standard HTTP status codes to indicate success or failure:

### Success Codes

- `200 OK`: Request succeeded
- `201 Created`: Resource created successfully


### Client Error Codes

- `400 Bad Request`: Invalid request parameters or body
- `401 Unauthorized`: Missing or invalid authentication token
- `403 Forbidden`: Insufficient permissions
- `404 Not Found`: Resource not found
- `429 Too Many Requests`: Rate limit exceeded


### Server Error Codes

- `500 Internal Server Error`: Server-side error
- `503 Service Unavailable`: Service temporarily unavailable


### Error Response Format


```json
{
  "errors": {
    "title": ["Title is required"],
    "duration": ["Duration must be a positive number"]
  }
}
```

## Support

Need help? We're here for you!

- **Email**: [support@moguplatform.com](mailto:support@moguplatform.com)
- **Help Center**: [https://help.moguplatform.com](https://help.moguplatform.com)


## Terms of Service

By using the MOGU Public API, you agree to our [Terms of Service](https://moguplatform.com/terms) and [Privacy Policy](https://moguplatform.com/privacy).

**Ready to get started?** Check out our [API Reference](/openapi) for detailed endpoint documentation.