RATIO MACHINA STARTER logo

MERCURY

Skills REST API

The Skills REST API provides complete management of executable skills that enhance persona capabilities. Skills enable AI personas to perform specific actions, access external systems, and provide specialized functionality beyond conversational responses.

Base URL & Authentication

Base URL: https://your-api-name.mercury.ratiomachina.com
Authentication: x-mercury-api-key: YOUR_API_KEY

List All Skills

GET /skills

Query Parameters

No query parameters supported. Returns all skills with count.

Response Example

{
  "skills": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "externalId": "skill123",
      "name": "Sentiment Analysis",
      "role": "sentimentAnalysis",
      "data": {"model": "advanced", "confidence_threshold": 0.8},
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  ],
  "count": 1
}

Create Skill

POST /skills

Request Body

{
  "name": "Sentiment Analysis",
  "externalId": "skill123",
  "role": "sentimentAnalysis",
  "data": {"model": "advanced"}
}

Response Example

{
  "skill": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "externalId": "skill123",
    "name": "Sentiment Analysis",
    "role": "sentimentAnalysis",
    "data": {"model": "advanced"},
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  }
}

Get Skill by ID

GET /skills/{id}

Path Parameters

  • id - Skill UUID or external ID

Query Parameters

No query parameters supported.

Response Example

{
  "skill": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "externalId": "skill123",
    "name": "Sentiment Analysis",
    "role": "sentimentAnalysis",
    "data": {"model": "advanced", "confidence_threshold": 0.8},
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  }
}

Update Skill

PUT /skills/{id}

Update skill configuration, parameters, or metadata. Changes create a new version for tracking purposes.

Request Body

{
  "name": "Updated Sentiment Analysis",
  "role": "sentimentAnalysis",
  "data": {"model": "premium", "confidence_threshold": 0.9}
}

Response Example

{
  "skill": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "externalId": "skill123",
    "name": "Updated Sentiment Analysis",
    "role": "sentimentAnalysis",
    "data": {"model": "premium", "confidence_threshold": 0.9},
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T11:45:00Z"
  }
}

Delete Skill

DELETE /skills/{id}

⚠️ Warning: This will permanently delete the skill.

Path Parameters

  • id - Skill UUID or external ID

Query Parameters

No query parameters supported.

Response Example

{
  "message": "Skill deleted successfully",
  "deletedSkill": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "externalId": "skill123",
    "name": "Sentiment Analysis",
    "role": "sentimentAnalysis"
  }
}

Execute Skill

POST /execute-skill

Execute a skill with specified parameters and context.

Request Body

{
  "skillId": "123e4567-e89b-12d3-a456-426614174000",
  "parameters": {"text": "I love this product!"},
  "context": {"conversationId": "conv789", "messageId": "msg456"}
}

Response Example

{
  "execution": {
    "id": "abc12345-e89b-12d3-a456-426614174000",
    "skillId": "123e4567-e89b-12d3-a456-426614174000",
    "status": "completed",
    "result": {"sentiment": "positive", "confidence": 0.95},
    "createdAt": "2024-01-15T16:30:00Z"
  }
}

Get Skill Executions

GET /skills/{id}/executions

Path Parameters

  • id - Skill UUID or external ID

Query Parameters

No query parameters supported.

Response Example

{
  "executions": [
    {
      "id": "abc12345-e89b-12d3-a456-426614174000",
      "skillId": "123e4567-e89b-12d3-a456-426614174000",
      "status": "completed",
      "result": {"sentiment": "positive", "confidence": 0.95},
      "createdAt": "2024-01-15T16:30:00Z"
    }
  ]
}

Get Skill Execution Detail

GET /skills/{id}/executions/{execution_id}

Path Parameters

  • id - Skill UUID or external ID
  • execution_id - Execution UUID

Response Example

{
  "execution": {
    "id": "abc12345-e89b-12d3-a456-426614174000",
    "skillId": "123e4567-e89b-12d3-a456-426614174000",
    "status": "completed",
    "parameters": {"text": "I love this product!"},
    "result": {"sentiment": "positive", "confidence": 0.95},
    "createdAt": "2024-01-15T16:30:00Z"
  }
}

Batch Archive Skills

POST /batch-ops/skills/archive

Archive multiple skills by their external IDs instead of deleting them. Archived skills retain all data.

Request Body

{
  "external_ids": [
    "skill123",
    "skill456"
  ]
}

Response Example

{
  "message": "2 skill(s) archived successfully",
  "archived": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "externalId": "skill123",
      "name": "Sentiment Analysis",
      "archived": true
    }
  ],
  "archived_count": 2,
  "already_archived_count": 0,
  "not_found_count": 0
}

Batch Delete Skills

DELETE /batch-ops/skills

Delete multiple skills by their external IDs.

⚠️ Warning: This will permanently delete the skills and all associated executions.

Request Body

{
  "external_ids": [
    "skill123",
    "skill456"
  ]
}

Response Example

{
  "message": "2 skill(s) deleted successfully",
  "deletedCount": 2,
  "deletedSkills": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "externalId": "skill123",
      "name": "Sentiment Analysis"
    }
  ],
  "notFound": []
}

Skills API Best Practices

Development & Testing

  • Use skill templates to accelerate development
  • Test skills thoroughly before deployment
  • Implement proper error handling and timeouts
  • Version skills for rollback capability

Monitoring & Optimization

  • Monitor execution performance and success rates
  • Use usage analytics to optimize skill parameters
  • Implement caching for frequently accessed data
  • Deactivate instead of deleting for safety
← Messages APIRPC APIs →
Transcend the hype with MERCURY by Ratio Machina