Profiles

Audience: Developers

Profiles API Contract

Overview

The Profiles API provides endpoints for managing research profiles.

Authentication:

• GET /v1/profiles and GET /v1/profiles/{profile} accept any valid X-API-Key (master or account).

• POST, PUT and DELETE profile endpoints require the master API key.

---

Get Profiles List (GET /v1/profiles)

List all available research profiles with their configurations.

Authentication: Master or account API key required

Example cURL:

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

Example Response:

{
  "profiles": [
    {
      "name": "INTERNAL",
      "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": "ESSENTIAL"
}

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:

curl --location 'https://stag-gl-deep-research.obrol.id/v1/profiles/ESSENTIAL'

Example Response:

{
  "name": "ESSENTIAL",
  "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:

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:

{
  "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

Optional params field — allow_inject_mcp_server (default: false):

Value	Meaning
true	Research requests may include non-UUID keys in mcp_config (inline MCP server definitions).
false or omitted (default)`	Inline MCP keys are rejected; UUID keys (registered MCP configs) remain valid.
Other types	Invalid; must be a JSON boolean when the key is present.

Example Response (201 Created):

{
  "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:

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:

{
  "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:

{
  "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:

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

Example Response:

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

Response Fields:

Field	Type	Description
message	string	Success message