Get Skill File

Retrieve a stored Skill file by path

Retrieves a stored Skill file by path from your workspace.

Base URL

https://api.ajan.io/skills/v1/{skillId}/files

Required Scopes

This endpoint requires the SKILL_API scope.

Parameters

Parameter	Type	Required	Description
`skillId`	string	Yes	UUID of the Skill to retrieve.
`path`	string	Yes	Relative path of the file inside the Skill, for example `references/template.md`. Maximum: 255 characters. Absolute paths, drive-prefixed paths, control characters, and `..` segments are rejected.

The file must be valid UTF-8 and no larger than 512 KB. Readable extensions are .md, .mdx, .txt, .py, .sh, .js, .ts, .json, .yaml, .yml, .toml, .csv, .xml, .xsd, .html, .css, and .svg. Binary and other unsupported files stay listed on Get Skill. This endpoint does not return their contents.

Example

javascript

const axios = require("axios");

async function getSkillFile(skillId, path) {
  const response = await axios.get(
    `https://api.ajan.io/skills/v1/${skillId}/files`,
    {
      params: { path },
      headers: {
        Authorization: "Bearer YOUR_API_KEY"
      }
    }
  );

  console.log("Content:", response.data.content);
}

getSkillFile(
  "550e8400-e29b-41d4-a716-446655440000",
  "references/template.md"
);

Response Format

Success Response (200 OK)

typescript

{
  path: string;
  sizeBytes: number;
  extension: string;
  hasScript: boolean;
  sha256: string;
  content: string;
}

Error Handling

Status Code	Description
400	Invalid Skill ID, invalid path, unsupported file type, invalid UTF-8, or file larger than 512 KB
401	Invalid or missing API key
403	Missing `SKILL_API` scope or Skills product access
404	Skill or file not found, or not accessible
429	Rate limit exceeded
500	Internal server error

OpenAPI

openapi: 3.0.0
info:
  title: ajan API
  version: 3.0.0
servers:
  - url: https://api.ajan.io
    description: Production
security:
  - bearerAuth: []
paths:
  /skills/v1/{skillId}/files:
    get:
      tags:
        - Skills
      summary: Get a Skill file
      description: Retrieves a stored Skill file by path from your workspace.
      operationId: getSkillFile
      parameters:
        - $ref: '#/components/parameters/SkillId'
        - name: path
          in: query
          required: true
          description: Relative path of the file inside the Skill.
          schema:
            type: string
            minLength: 1
            maxLength: 255
      responses:
        '200':
          description: File returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SkillFileContent'
        '400':
          description: >-
            Invalid Skill ID, invalid path, unsupported file type, invalid
            UTF-8, or file larger than 512 KB
        '401':
          description: Invalid or missing API key
        '403':
          description: Missing required scope or access
        '404':
          description: Skill or file not found
        '429':
          description: Rate limit exceeded
        '500':
          description: Internal server error
components:
  parameters:
    SkillId:
      name: skillId
      in: path
      required: true
      description: UUID of the Skill.
      schema:
        type: string
        format: uuid
  schemas:
    SkillFileContent:
      allOf:
        - $ref: '#/components/schemas/SkillFile'
        - type: object
          required:
            - content
          properties:
            content:
              type: string
              description: UTF-8 file contents.
    SkillFile:
      type: object
      required:
        - path
        - sizeBytes
        - extension
        - hasScript
        - sha256
      properties:
        path:
          type: string
          description: Relative path inside the Skill.
        sizeBytes:
          type: integer
          description: File size in bytes.
        extension:
          type: string
          description: Lowercase file extension, including the leading dot.
        hasScript:
          type: boolean
          description: Whether the file is a script file (`.py`, `.sh`, `.js`, or `.ts`).
        sha256:
          type: string
          description: Lowercase SHA-256 hash of the original file bytes.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: API key as Bearer token. Format "Bearer YOUR_API_KEY"