SoftSync AI MCP Skills API

openapi: 3.2.0
info:
  title: Softsync MCP Skills API
  description: '## Introduction


    The Softsync Platform API


    This API lets you read and write your Softsync data from your own applications. Authenticate with a personal API key created in **Settings → API Keys**, sent as the `x-api-key` header.


    **New here?** Read **Concepts** first, then **Authentication**, then **Quickstart: full cycle** — it walks the whole thing end to end. **Objects**, **Records**, **Groups & Views** and **Notes** cover each area in depth, and **Code Generation** shows how to turn this document into a typed client.


    To try a request from this page, paste your API key into the **Authentication** panel on the right.


    ## Support


    If you need help with API access or integration details, contact contact@softsync.ai.'
  version: 0.1.0
  contact: {}
servers: []
security:
- x-api-key: []
tags:
- name: MCP Skills
paths:
  /mcp/skills:
    get:
      description: Returns all available MCP skill instructions. Each skill contains detailed guidance on how to use the related API tools effectively, including required call order, parameter formats, and best practices. Always call this endpoint first to understand how to use other tools correctly.
      operationId: getMcpSkills
      parameters:
      - name: x-workspace-id
        in: header
        description: Workspace ID
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Skill instructions loaded successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/McpSkillsResponseDto'
      security:
      - bearer: []
      summary: Load skill instructions — CALL THIS FIRST before using any other tools.
      tags:
      - MCP Skills
      x-feature: mcp
  /mcp/skills/{skillName}:
    get:
      operationId: getMcpSkill
      parameters:
      - name: x-workspace-id
        in: header
        description: Workspace ID
        required: true
        schema:
          type: string
      - name: skillName
        required: true
        in: path
        description: 'Skill name: records, messages, notes, tables, or groups_and_views'
        schema:
          type: string
      responses:
        '200':
          description: Skill instructions loaded successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/McpSkillDto'
        '404':
          description: Skill not found
      security:
      - bearer: []
      summary: Load a specific skill by name — provides detailed instructions for a single…
      tags:
      - MCP Skills
      x-feature: mcp
  /mcp/skills/{skillName}/references/{referenceName}:
    get:
      operationId: getMcpSkillReference
      parameters:
      - name: x-workspace-id
        in: header
        description: Workspace ID
        required: true
        schema:
          type: string
      - name: skillName
        required: true
        in: path
        description: Skill name, such as records
        schema:
          type: string
      - name: referenceName
        required: true
        in: path
        description: Reference name, such as searching-records
        schema:
          type: string
      responses:
        '200':
          description: Reference loaded successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/McpSkillReferenceContentDto'
        '404':
          description: Skill or reference not found
      security:
      - bearer: []
      summary: Load one detailed guide from a skill — listed in that skill's references
      tags:
      - MCP Skills
      x-feature: mcp
components:
  schemas:
    McpSkillReferenceDto:
      type: object
      properties:
        name:
          type: string
          description: Reference name, used to load it
        summary:
          type: string
          description: When to read this reference
      required:
      - name
      - summary
    McpSkillsResponseDto:
      type: object
      properties:
        skills:
          description: Available skills — load these instructions before calling other tools
          type: array
          items:
            $ref: '#/components/schemas/McpSkillDto'
      required:
      - skills
    McpSkillReferenceContentDto:
      type: object
      properties:
        content:
          type: string
          description: The full guide, as Markdown
      required:
      - content
    McpSkillDto:
      type: object
      properties:
        name:
          type: string
          description: Unique skill identifier
        description:
          type: string
          description: Short description of the skill
        instructions:
          type: string
          description: Detailed instructions for using the skill and its related tools
        relatedTools:
          description: List of related tool/operation names this skill covers
          type: array
          items:
            type: string
        references:
          description: Detailed guides for this skill. Load one with GET /mcp/skills/{skillName}/references/{referenceName}.
          type: array
          items:
            $ref: '#/components/schemas/McpSkillReferenceDto'
      required:
      - name
      - description
      - instructions
      - relatedTools
      - references
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: JWT
      type: http
    x-api-key:
      type: apiKey
      in: header
      name: x-api-key