Custom Agents

Onboard Custom Agent

post

Onboard a custom agent from .ncp package (admin-only).

This endpoint is called by ncp onboard command. Unlike SDK deploy, custom agents:

• Run integrated within platform (no container)

• Are available to users based on role permissions

• Go directly to ACTIVE status (admin upload = immediate activation)

Args: file: .ncp package file (tar.gz) update: Optional agent name to update username: Authenticated username from API key db: Database session

Returns: Onboard status and agent information

Authorizations

Bearer Token

AuthorizationstringRequired

Enter your JWT token (without 'Bearer ' prefix)

Query parameters

updateany ofOptional

stringOptional

or

nullOptional

Header parameters

authorizationany ofOptional

stringOptional

or

nullOptional

Body

multipart/form-data

filestringRequired

Responses

200

Successful Response

application/json

Response for agent onboarding.

messagestringRequired

agent_idintegerRequired

agent_namestringRequired

statusstring · enumRequired

Status of a custom agent.

Current release uses: ACTIVE, DISABLED Future release adds: PENDING, REJECTED (for UI approval workflow)

Possible values:

422

Validation Error

application/json

post

/api/v1/custom_agents/onboard

HTTPcURLJavaScriptPython

POST /api/v1/custom_agents/onboard HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: multipart/form-data
Accept: */*
Content-Length: 15

{
  "file": "text"
}

{
  "message": "text",
  "agent_id": 1,
  "agent_name": "text",
  "status": "PENDING"
}

List Custom Agents

get

List all custom agents (admin-only).

Args: username: Authenticated username db: Database session

Returns: List of all custom agents

Authorizations

Bearer Token

AuthorizationstringRequired

Enter your JWT token (without 'Bearer ' prefix)

Header parameters

authorizationany ofOptional

stringOptional

or

nullOptional

Responses

200

Successful Response

application/json

Response for listing custom agents.

totalintegerRequired

422

Validation Error

application/json

get

/api/v1/custom_agents/list

HTTPcURLJavaScriptPython

GET /api/v1/custom_agents/list HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "agents": [
    {
      "agent_id": 1,
      "name": "text",
      "description": "text",
      "status": "PENDING",
      "version": "text",
      "submitted_by": "text",
      "created_at": "2026-04-01T16:29:42.943Z",
      "updated_at": "2026-04-01T16:29:42.943Z",
      "error_message": "text",
      "reviewed_by": "text",
      "reviewed_at": "2026-04-01T16:29:42.943Z",
      "rejection_reason": "text",
      "feedback_message": "text"
    }
  ],
  "total": 1
}

Get Custom Agent

get

Get details of a custom agent (admin-only).

Args: agent_name: Name of the agent username: Authenticated username db: Database session

Returns: Agent details

Authorizations

Bearer Token

AuthorizationstringRequired

Enter your JWT token (without 'Bearer ' prefix)

Path parameters

agent_namestringRequired

Header parameters

authorizationany ofOptional

stringOptional

or

nullOptional

Responses

200

Successful Response

application/json

Response for agent status/details.

agent_idintegerRequired

namestringRequired

descriptionany ofOptional

stringOptional

or

nullOptional

statusstring · enumRequired

Status of a custom agent.

Current release uses: ACTIVE, DISABLED Future release adds: PENDING, REJECTED (for UI approval workflow)

Possible values:

versionstringRequired

submitted_bystringRequired

created_atany ofOptional

string · date-timeOptional

or

nullOptional

updated_atany ofOptional

string · date-timeOptional

or

nullOptional

error_messageany ofOptional

stringOptional

or

nullOptional

reviewed_byany ofOptional

stringOptional

or

nullOptional

reviewed_atany ofOptional

string · date-timeOptional

or

nullOptional

rejection_reasonany ofOptional

stringOptional

or

nullOptional

feedback_messageany ofOptional

stringOptional

or

nullOptional

422

Validation Error

application/json

get

/api/v1/custom_agents/{agent_name}

HTTPcURLJavaScriptPython

GET /api/v1/custom_agents/{agent_name} HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "agent_id": 1,
  "name": "text",
  "description": "text",
  "status": "PENDING",
  "version": "text",
  "submitted_by": "text",
  "created_at": "2026-04-01T16:29:42.943Z",
  "updated_at": "2026-04-01T16:29:42.943Z",
  "error_message": "text",
  "reviewed_by": "text",
  "reviewed_at": "2026-04-01T16:29:42.943Z",
  "rejection_reason": "text",
  "feedback_message": "text"
}

Remove Custom Agent

delete

Remove a custom agent (admin-only).

Args: agent_name: Name of the agent username: Authenticated username db: Database session

Returns: Removal confirmation

Authorizations

Bearer Token

AuthorizationstringRequired

Enter your JWT token (without 'Bearer ' prefix)

Path parameters

agent_namestringRequired

Header parameters

authorizationany ofOptional

stringOptional

or

nullOptional

Responses

200

Successful Response

application/json

Response for agent removal.

messagestringRequired

agent_namestringRequired

422

Validation Error

application/json

delete

/api/v1/custom_agents/{agent_name}

HTTPcURLJavaScriptPython

DELETE /api/v1/custom_agents/{agent_name} HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "message": "text",
  "agent_name": "text"
}

Disable Custom Agent

post

Disable a custom agent (admin-only).

Disabled agents are not loaded into the orchestrator.

Args: agent_name: Name of the agent username: Authenticated username db: Database session

Returns: Updated agent status

Authorizations

Bearer Token

AuthorizationstringRequired

Enter your JWT token (without 'Bearer ' prefix)

Path parameters

agent_namestringRequired

Header parameters

authorizationany ofOptional

stringOptional

or

nullOptional

Responses

200

Successful Response

application/json

Response for enabling/disabling agent.

messagestringRequired

agent_namestringRequired

statusstring · enumRequired

Status of a custom agent.

Current release uses: ACTIVE, DISABLED Future release adds: PENDING, REJECTED (for UI approval workflow)

Possible values:

422

Validation Error

application/json

post

/api/v1/custom_agents/{agent_name}/disable

HTTPcURLJavaScriptPython

POST /api/v1/custom_agents/{agent_name}/disable HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "message": "text",
  "agent_name": "text",
  "status": "PENDING"
}

Enable Custom Agent

post

Enable a disabled custom agent (admin-only).

Args: agent_name: Name of the agent username: Authenticated username db: Database session

Returns: Updated agent status

Authorizations

Bearer Token

AuthorizationstringRequired

Enter your JWT token (without 'Bearer ' prefix)

Path parameters

agent_namestringRequired

Header parameters

authorizationany ofOptional

stringOptional

or

nullOptional

Responses

200

Successful Response

application/json

Response for enabling/disabling agent.

messagestringRequired

agent_namestringRequired

statusstring · enumRequired

Status of a custom agent.

Current release uses: ACTIVE, DISABLED Future release adds: PENDING, REJECTED (for UI approval workflow)

Possible values:

422

Validation Error

application/json

post

/api/v1/custom_agents/{agent_name}/enable

HTTPcURLJavaScriptPython

POST /api/v1/custom_agents/{agent_name}/enable HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "message": "text",
  "agent_name": "text",
  "status": "PENDING"
}

Get Custom Agents

get

List all custom agents for Admin (status = 'ACTIVE', 'PENDING', 'REJECTED').

Args: username: Authenticated username db: Database session

Returns: List of all custom agents for admin

Authorizations

Bearer Token

AuthorizationstringRequired

Enter your JWT token (without 'Bearer ' prefix)

Header parameters

authorizationany ofOptional

stringOptional

or

nullOptional

Responses

200

Successful Response

application/json

Response for listing custom agents for Admin.

totalintegerRequired

422

Validation Error

application/json

get

/api/v1/custom_agents/admin/list

HTTPcURLJavaScriptPython

GET /api/v1/custom_agents/admin/list HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "agents": [
    {
      "agent_id": 1,
      "name": "text",
      "description": "text",
      "status": "PENDING",
      "version": "text",
      "submitted_by": "text",
      "created_at": "2026-04-01T16:29:42.943Z",
      "updated_at": "2026-04-01T16:29:42.943Z",
      "error_message": "text",
      "reviewed_by": "text",
      "reviewed_at": "2026-04-01T16:29:42.943Z",
      "rejection_reason": "text",
      "status_changed_by": "text",
      "status_changed_at": "2026-04-01T16:29:42.943Z",
      "submitted_at": "2026-04-01T16:29:42.943Z",
      "assigned_roles": [
        "text"
      ],
      "feedback_message": "text"
    }
  ],
  "total": 1
}

Get Custom Agents By User

get

Get custom agents submitted by the authenticated user.

Args: username: Authenticated username db: Database session

Returns: List of all custom agents for users

Authorizations

Bearer Token

AuthorizationstringRequired

Enter your JWT token (without 'Bearer ' prefix)

Header parameters

authorizationany ofOptional

stringOptional

or

nullOptional

Responses

200

Successful Response

application/json

Response for listing custom agents.

totalintegerRequired

422

Validation Error

application/json

get

/api/v1/custom_agents/user/my-agent

HTTPcURLJavaScriptPython

GET /api/v1/custom_agents/user/my-agent HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "agents": [
    {
      "agent_id": 1,
      "name": "text",
      "description": "text",
      "status": "PENDING",
      "version": "text",
      "submitted_by": "text",
      "created_at": "2026-04-01T16:29:42.943Z",
      "updated_at": "2026-04-01T16:29:42.943Z",
      "error_message": "text",
      "reviewed_by": "text",
      "reviewed_at": "2026-04-01T16:29:42.943Z",
      "rejection_reason": "text",
      "feedback_message": "text"
    }
  ],
  "total": 1
}

Submit Custom Agent

post

Upload a new custom agent.

• Admin: auto-active, extracted, dependencies installed

• User: pending approval

Authorizations

Bearer Token

AuthorizationstringRequired

Enter your JWT token (without 'Bearer ' prefix)

Header parameters

authorizationany ofOptional

stringOptional

or

nullOptional

Body

multipart/form-data

filestringRequired

Responses

200

Successful Response

application/json

Response for agent onboarding.

messagestringRequired

agent_idintegerRequired

agent_namestringRequired

statusstring · enumRequired

Status of a custom agent.

Current release uses: ACTIVE, DISABLED Future release adds: PENDING, REJECTED (for UI approval workflow)

Possible values:

422

Validation Error

application/json

post

/api/v1/custom_agents/user/submit

HTTPcURLJavaScriptPython

POST /api/v1/custom_agents/user/submit HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: multipart/form-data
Accept: */*
Content-Length: 15

{
  "file": "text"
}

{
  "message": "text",
  "agent_id": 1,
  "agent_name": "text",
  "status": "PENDING"
}

Update Custom Agent

post

Upload a new version of a custom agent.

Args: agent_id: ID of the agent username: Authenticated username db: Database session

Returns: Response message and status

Authorizations

Bearer Token

AuthorizationstringRequired

Enter your JWT token (without 'Bearer ' prefix)

Path parameters

agent_idstringRequired

Header parameters

authorizationany ofOptional

stringOptional

or

nullOptional

Body

multipart/form-data

filestringRequired

Responses

200

Successful Response

application/json

Response for agent onboarding.

messagestringRequired

agent_idintegerRequired

agent_namestringRequired

versionstringRequired

statusstring · enumRequired

Status of a custom agent.

Current release uses: ACTIVE, DISABLED Future release adds: PENDING, REJECTED (for UI approval workflow)

Possible values:

422

Validation Error

application/json

post

/api/v1/custom_agents/{agent_id}/version

HTTPcURLJavaScriptPython

POST /api/v1/custom_agents/{agent_id}/version HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: multipart/form-data
Accept: */*
Content-Length: 15

{
  "file": "text"
}

{
  "message": "text",
  "agent_id": 1,
  "agent_name": "text",
  "version": "text",
  "status": "PENDING"
}

Approve Custom Agent

post

Approve a custom agent (admin-only). extract to runtime directory

Args: agent_id: ID of the agent username: Authenticated username db: Database session

Returns: Approval confirmation

Authorizations

Bearer Token

AuthorizationstringRequired

Enter your JWT token (without 'Bearer ' prefix)

Path parameters

agent_idstringRequired

Header parameters

authorizationany ofOptional

stringOptional

or

nullOptional

Responses

200

Successful Response

application/json

Response for enabling/disabling agent.

messagestringRequired

agent_namestringRequired

statusstring · enumRequired

Status of a custom agent.

Current release uses: ACTIVE, DISABLED Future release adds: PENDING, REJECTED (for UI approval workflow)

Possible values:

422

Validation Error

application/json

post

/api/v1/custom_agents/{agent_id}/approve

HTTPcURLJavaScriptPython

POST /api/v1/custom_agents/{agent_id}/approve HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "message": "text",
  "agent_name": "text",
  "status": "PENDING"
}

Decline Custom Agent

post

Decline a custom agent (admin-only).

Args: agent_id: ID of the agent username: Authenticated username db: Database session

Returns: Decline confirmation

Authorizations

Bearer Token

AuthorizationstringRequired

Enter your JWT token (without 'Bearer ' prefix)

Path parameters

agent_idstringRequired

Header parameters

authorizationany ofOptional

stringOptional

or

nullOptional

Body

application/json

feedbackstringRequired

Responses

200

Successful Response

application/json

Response for enabling/disabling agent.

messagestringRequired

agent_namestringRequired

statusstring · enumRequired

Status of a custom agent.

Current release uses: ACTIVE, DISABLED Future release adds: PENDING, REJECTED (for UI approval workflow)

Possible values:

422

Validation Error

application/json

post

/api/v1/custom_agents/{agent_id}/decline

HTTPcURLJavaScriptPython

POST /api/v1/custom_agents/{agent_id}/decline HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 19

{
  "feedback": "text"
}

{
  "message": "text",
  "agent_name": "text",
  "status": "PENDING"
}

Remove Custom Agent

delete

Remove a custom agent.

Args: agent_name: Name of the agent username: Authenticated username db: Database session

Returns: Removal confirmation

Authorizations

Bearer Token

AuthorizationstringRequired

Enter your JWT token (without 'Bearer ' prefix)

Path parameters

agent_namestringRequired

Header parameters

authorizationany ofOptional

stringOptional

or

nullOptional

Responses

200

Successful Response

application/json

Response for agent removal.

messagestringRequired

agent_namestringRequired

422

Validation Error

application/json

delete

/api/v1/custom_agents/user/{agent_name}

HTTPcURLJavaScriptPython

DELETE /api/v1/custom_agents/user/{agent_name} HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "message": "text",
  "agent_name": "text"
}

Feedback Custom Agent

post

Submit feedback for a custom agent (admin-only).

Args: agent_id (str): description feedback_request (AgentFeedbackRequest): description username (str, optional): description. Defaults to Depends(verify_api_token). db (Session, optional): description. Defaults to Depends(get_db).

Returns: feedback submit confirm

Authorizations

Bearer Token

AuthorizationstringRequired

Enter your JWT token (without 'Bearer ' prefix)

Path parameters

agent_idstringRequired

Header parameters

authorizationany ofOptional

stringOptional

or

nullOptional

Body

application/json

messagestringRequired

feedback_typestringRequired

Responses

200

Successful Response

application/json

Response for agent feedback submission.

messagestringRequired

agent_namestringRequired

422

Validation Error

application/json

post

/api/v1/custom_agents/{agent_id}/feedback

HTTPcURLJavaScriptPython

POST /api/v1/custom_agents/{agent_id}/feedback HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 41

{
  "message": "text",
  "feedback_type": "text"
}

{
  "message": "text",
  "agent_name": "text"
}

Download Custom Agent

get

Download custom agent package (admin and owner).

Args: agent_id (str): ID of the agent username (str, optional): Authenticated username. Defaults to Depends(verify_api_token). db (Session, optional): Database session. Defaults to Depends(get_db).

Returns: FileResponse: The .ncp package file for download

Authorizations

Bearer Token

AuthorizationstringRequired

Enter your JWT token (without 'Bearer ' prefix)

Path parameters

agent_idstringRequired

Header parameters

authorizationany ofOptional

stringOptional

or

nullOptional

Responses

200

Successful Response

application/json

Response for agent package download.

messagestringRequired

agent_namestringRequired

422

Validation Error

application/json

get

/api/v1/custom_agents/{agent_id}/download

HTTPcURLJavaScriptPython

GET /api/v1/custom_agents/{agent_id}/download HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "message": "text",
  "agent_name": "text"
}

Can Submit Custom Agent

get

Check if the user can submit a new agent.

Args: username (str, optional): The username of the authenticated user. Defaults to Depends(verify_api_token). db (Session, optional): The database session. Defaults to Depends(get_db).

Returns: CustomAgentSubmitResponse: The response indicating if the user have the permission to submit a new agent.

Authorizations

Bearer Token

AuthorizationstringRequired

Enter your JWT token (without 'Bearer ' prefix)

Header parameters

authorizationany ofOptional

stringOptional

or

nullOptional

Responses

200

Successful Response

application/json

Response for agent submission.

submitAgentbooleanRequired

422

Validation Error

application/json

get

/api/v1/custom_agents/user/can-submit-agent

HTTPcURLJavaScriptPython

GET /api/v1/custom_agents/user/can-submit-agent HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "submitAgent": true
}