# Profiles

**Audience:** Developers

## Profiles API Contract

### Overview

The Profiles API provides endpoints for managing research profiles. All profile management endpoints require the master API key.

**Authentication:** All endpoints require the `X-API-Key` header with the master API key (from `GL_DEEP_RESEARCH_MASTER_API_KEY` environment variable).

***

### Get Profiles List (`GET /v1/profiles`)

List all available research profiles with their configurations.

**Authentication:** Master API key required

**Example cURL:**

```bash
curl --location 'https://stag-gl-deep-research.obrol.id/v1/profiles' \
  -H 'X-API-Key: your-master-api-key'
```

**Example Response:**

```json
{
  "profiles": [
    {
      "name": "TONGYI",
      "provider": "tongyi",
      "params": {
        "model": "Alibaba-NLP/Tongyi-DeepResearch-30B-A3B",
        "max_tokens": 10000,
        "temperature": 0.6,
        "max_depth": 7,
        "timeout_seconds": 900
      },
      "description": "Tongyi Deep Research Agent"
    }, ...
  ],
  "default_profile": "GPTR-QUICK"
}
```

**Response Fields:**

| Field                    | Type             | Description                          |
| ------------------------ | ---------------- | ------------------------------------ |
| `profiles`               | array of objects | List of available profiles           |
| `profiles[].name`        | string           | Profile name identifier              |
| `profiles[].provider`    | string           | Provider type:`"tongyi"` or `"gptr"` |
| `profiles[].params`      | object           | Profile-specific parameters          |
| `profiles[].description` | string           | Profile description                  |
| `default_profile`        | string           | Default profile to be used           |

***

### Get Profile (`GET /v1/profiles/{profile}`)

Get a specific profile by its name identifier.

**Example cURL:**

```bash
curl --location 'https://stag-gl-deep-research.obrol.id/v1/profiles/GPTR-QUICK'
```

**Example Response:**

```json
{
  "name": "GPTR-QUICK",
  "provider": "gptr",
  "params": {
    "model": "Alibaba-NLP/Tongyi-DeepResearch-30B-A3B",
    "max_tokens": 10000,
    "temperature": 0.6,
    "max_depth": 7,
    "timeout_seconds": 900
  },
  "description": "GPT-Researcher Quick"
}
```

**Response Fields:**

| Field         | Type   | Description                          |
| ------------- | ------ | ------------------------------------ |
| `name`        | string | Profile name identifier              |
| `provider`    | string | Provider type:`"tongyi"` or `"gptr"` |
| `params`      | object | Profile-specific parameters          |
| `description` | string | Profile description                  |

***

### Create Profile (`POST /v1/profiles`)

Create a new research profile.

**Example cURL:**

```bash
curl -X POST 'https://stag-gl-deep-research.obrol.id/v1/profiles' \
  -H "Content-Type: application/json" \
  -d '{
    "name": "MY_PROFILE",
    "provider": "gptr",
    "params": {
      "config_data": {
        "RETRIEVER": "custom",
        "SCRAPER": "smart_search"
      },
      "report_type": "research_report"
    },
    "description": "My custom profile"
  }'
```

**Example JSON Request:**

```json
{
  "name": "MY_PROFILE",
  "provider": "gptr",
  "params": {
    "config_data": {
      "RETRIEVER": "custom",
      "SCRAPER": "smart_search"
    },
    "report_type": "research_report"
  },
  "description": "My custom profile"
}
```

**Request Fields:**

| Field         | Type   | Required | Description                          |
| ------------- | ------ | -------- | ------------------------------------ |
| `name`        | string | Yes      | Profile identifier                   |
| `provider`    | string | Yes      | Provider type:`"tongyi"` or `"gptr"` |
| `params`      | object | Yes      | Profile-specific parameters          |
| `description` | string | No       | Profile description                  |

**Example Response (201 Created):**

```json
{
  "profile": {
    "name": "MY_PROFILE",
    "provider": "gptr",
    "params": {
      "config_data": {
        "RETRIEVER": "custom",
        "SCRAPER": "smart_search"
      },
      "report_type": "research_report"
    },
    "description": "My custom profile"
  },
  "message": "Profile created successfully"
}
```

***

### Update Profile (`PUT /v1/profiles/{profile}`)

Update an existing research profile.

**Example cURL:**

```bash
curl -X PUT 'https://stag-gl-deep-research.obrol.id/v1/profiles/MY_PROFILE' \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "gptr",
    "params": {
      "config_data": {
        "RETRIEVER": "custom",
        "SCRAPER": "smart_search"
      },
      "report_type": "research_report"
    },
    "description": "Updated profile description"
  }'
```

**Example JSON Request:**

```json
{
  "provider": "gptr",
  "params": {
    "config_data": {
      "RETRIEVER": "custom",
      "SCRAPER": "smart_search"
    },
    "report_type": "research_report"
  },
  "description": "Updated profile description"
}
```

**Request Fields:**

| Field         | Type   | Required | Description                          |
| ------------- | ------ | -------- | ------------------------------------ |
| `provider`    | string | No       | Provider type:`"tongyi"` or `"gptr"` |
| `params`      | object | No       | Profile-specific parameters          |
| `description` | string | No       | Profile description                  |

**Example Response:**

```json
{
  "name": "MY_PROFILE",
  "provider": "gptr",
  "params": {
    "config_data": {
      "RETRIEVER": "custom",
      "SCRAPER": "smart_search"
    },
    "report_type": "research_report"
  },
  "description": "Updated profile description"
}
```

***

### Delete Profile (`DELETE /v1/profiles/{profile}`)

Delete a research profile by name.

**Example cURL:**

```bash
curl -X DELETE 'https://stag-gl-deep-research.obrol.id/v1/profiles/MY_PROFILE'
```

**Example Response:**

```json
{
  "message": "Profile 'MY_PROFILE' deleted successfully"
}
```

**Response Fields:**

| Field     | Type   | Description     |
| --------- | ------ | --------------- |
| `message` | string | Success message |
