Letta API — Templates

naftiko: "1.0.0-alpha2"

info:
  label: "Letta API — Templates"
  description: >-
    Templates — reusable agent templates for instantiation. 21 operations. Lead operation: Create Agents from Template. Self-contained Naftiko capability covering one Letta business surface.
  tags:
    - Letta
    - Stateful Agents
    - Templates
  created: "2026-05-08"
  modified: "2026-05-22"

binds:
  - namespace: env
    keys:
      LETTA_API_KEY: LETTA_API_KEY

capability:

  consumes:
    - type: http
      namespace: "letta-templates"
      baseUri: "https://api.letta.com"
      description: "Letta API — Templates business capability. Self-contained, no shared references."
      authentication:
        type: bearer
        token: "{{env.LETTA_API_KEY}}"
      resources:
        - name: "templates-by-id-by-id-agents"
          path: "/v1/templates/{project_id}/{template_version}/agents"
          operations:
            - name: "templates_createagentsfromtemplate"
              method: POST
              description: "Create Agents from Template"
              inputParameters:
                - name: "project_id"
                  in: path
                  type: string
                  required: true
                  description: "The project id"
                - name: "template_version"
                  in: path
                  type: string
                  required: true
                  description: "The template version, formatted as {template-name}:{version-number} or {template-name}:latest. This endpoint is not available for self-hosted Letta."
                - name: "body"
                  in: body
                  type: object
                  required: true
                  description: "Body"
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
        - name: "templates-by-id-agents"
          path: "/v1/templates/{template_version}/agents"
          operations:
            - name: "templates_createagentsfromtemplatenoproject"
              method: POST
              description: "Create Agents from Template"
              inputParameters:
                - name: "template_version"
                  in: path
                  type: string
                  required: true
                  description: "The template version, formatted as {template-name}:{version-number} or {template-name}:latest. This endpoint is not available for self-hosted Letta."
                - name: "body"
                  in: body
                  type: object
                  required: true
                  description: "Body"
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
        - name: "templates"
          path: "/v1/templates"
          operations:
            - name: "templates_listtemplates"
              method: GET
              description: "List Templates (Cloud-only)"
              inputParameters:
                - name: "offset"
                  in: query
                  type: string
                  required: false
                  description: "offset parameter"
                - name: "exact"
                  in: query
                  type: string
                  required: false
                  description: "Whether to search for an exact name match"
                - name: "limit"
                  in: query
                  type: string
                  required: false
                  description: "limit parameter"
                - name: "version"
                  in: query
                  type: string
                  required: false
                  description: "Specify the version you want to return, otherwise will return the latest version"
                - name: "template_id"
                  in: query
                  type: string
                  required: false
                  description: "template_id parameter"
                - name: "name"
                  in: query
                  type: string
                  required: false
                  description: "name parameter"
                - name: "search"
                  in: query
                  type: string
                  required: false
                  description: "search parameter"
                - name: "project_slug"
                  in: query
                  type: string
                  required: false
                  description: "project_slug parameter"
                - name: "project_id"
                  in: query
                  type: string
                  required: false
                  description: "project_id parameter"
                - name: "sort_by"
                  in: query
                  type: string
                  required: false
                  description: "sort_by parameter"
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
            - name: "templates_createtemplatenoproject"
              method: POST
              description: "Create Template (Cloud-only)"
              inputParameters:
                - name: "body"
                  in: body
                  type: object
                  required: true
                  description: "Body"
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
        - name: "templates-by-id-save"
          path: "/v1/templates/{template_name}/save"
          operations:
            - name: "templates_savetemplateversionnoproject"
              method: POST
              description: "Save Template Version (Cloud-only)"
              inputParameters:
                - name: "template_name"
                  in: path
                  type: string
                  required: true
                  description: "The template version, formatted as {template-name}, any version appended will be ignored"
                - name: "body"
                  in: body
                  type: object
                  required: true
                  description: "Body"
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
        - name: "templates-by-id-by-id"
          path: "/v1/templates/{project_id}/{template_name}"
          operations:
            - name: "templates_savetemplateversion"
              method: POST
              description: "Save Template Version (Cloud-only)"
              inputParameters:
                - name: "project_id"
                  in: path
                  type: string
                  required: true
                  description: "The project id"
                - name: "template_name"
                  in: path
                  type: string
                  required: true
                  description: "The template version, formatted as {template-name}, any version appended will be ignored"
                - name: "body"
                  in: body
                  type: object
                  required: true
                  description: "Body"
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
            - name: "templates_deletetemplate"
              method: DELETE
              description: "Delete Template (Cloud-only)"
              inputParameters:
                - name: "project_id"
                  in: path
                  type: string
                  required: true
                  description: "The project id"
                - name: "template_name"
                  in: path
                  type: string
                  required: true
                  description: "The template name (without version)"
                - name: "body"
                  in: body
                  type: object
                  required: true
                  description: "Body"
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
        - name: "templates-by-id-by-id-snapshot"
          path: "/v1/templates/{project_id}/{template_version}/snapshot"
          operations:
            - name: "templates_gettemplatesnapshot"
              method: GET
              description: "Get Template Snapshot (Cloud-only)"
              inputParameters:
                - name: "project_id"
                  in: path
                  type: string
                  required: true
                  description: "The project id"
                - name: "template_version"
                  in: path
                  type: string
                  required: true
                  description: "The template version, formatted as {template-name}:{version-number} or {template-name}:latest"
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
            - name: "templates_setcurrenttemplatefromsnapshot"
              method: PUT
              description: "Set Current Template from Snapshot (Cloud-only)"
              inputParameters:
                - name: "project_id"
                  in: path
                  type: string
                  required: true
                  description: "The project id"
                - name: "template_version"
                  in: path
                  type: string
                  required: true
                  description: "The template name with :dev version (e.g., my-template:dev)"
                - name: "body"
                  in: body
                  type: object
                  required: true
                  description: "Body"
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
        - name: "templates-by-id-by-id-fork"
          path: "/v1/templates/{project_id}/{template_version}/fork"
          operations:
            - name: "templates_forktemplate"
              method: POST
              description: "Fork Template (Cloud-only)"
              inputParameters:
                - name: "project_id"
                  in: path
                  type: string
                  required: true
                  description: "The project id"
                - name: "template_version"
                  in: path
                  type: string
                  required: true
                  description: "The template version, formatted as {template-name}:{version-number} or {template-name}:latest"
                - name: "body"
                  in: body
                  type: object
                  required: true
                  description: "Body"
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
        - name: "templates-by-id"
          path: "/v1/templates/{project_id}"
          operations:
            - name: "templates_createtemplate"
              method: POST
              description: "Create Template (Cloud-only)"
              inputParameters:
                - name: "project_id"
                  in: path
                  type: string
                  required: true
                  description: "The project id"
                - name: "body"
                  in: body
                  type: object
                  required: true
                  description: "Body"
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
        - name: "templates-by-id"
          path: "/v1/templates/{template_name}"
          operations:
            - name: "templates_deletetemplatenoproject"
              method: DELETE
              description: "Delete Template (Cloud-only)"
              inputParameters:
                - name: "template_name"
                  in: path
                  type: string
                  required: true
                  description: "The template name (without version)"
                - name: "body"
                  in: body
                  type: object
                  required: true
                  description: "Body"
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
            - name: "templates_updatecurrenttemplatefromagentfilenoproject"
              method: PATCH
              description: "Update Current Template from Agent File (Cloud-only)"
              inputParameters:
                - name: "template_name"
                  in: path
                  type: string
                  required: true
                  description: "The template name (without version)"
                - name: "body"
                  in: body
                  type: object
                  required: true
                  description: "Body"
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
        - name: "templates-by-id-by-id-name"
          path: "/v1/templates/{project_id}/{template_name}/name"
          operations:
            - name: "templates_renametemplate"
              method: PATCH
              description: "Rename Template (Cloud-only)"
              inputParameters:
                - name: "project_id"
                  in: path
                  type: string
                  required: true
                  description: "The project id"
                - name: "template_name"
                  in: path
                  type: string
                  required: true
                  description: "The current template name (version will be automatically stripped if included)"
                - name: "body"
                  in: body
                  type: object
                  required: true
                  description: "Body"
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
        - name: "templates-by-id-by-id-description"
          path: "/v1/templates/{project_id}/{template_name}/description"
          operations:
            - name: "templates_updatetemplatedescription"
              method: PATCH
              description: "Update Template Description (Cloud-only)"
              inputParameters:
                - name: "project_id"
                  in: path
                  type: string
                  required: true
                  description: "The project id"
                - name: "template_name"
                  in: path
                  type: string
                  required: true
                  description: "The template name (version will be automatically stripped if included)"
                - name: "body"
                  in: body
                  type: object
                  required: true
                  description: "Body"
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
        - name: "templates-by-id-by-id-versions"
          path: "/v1/templates/{project_id}/{name}/versions"
          operations:
            - name: "templates_listtemplateversions"
              method: GET
              description: "List Template Versions (Cloud-only)"
              inputParameters:
                - name: "project_id"
                  in: path
                  type: string
                  required: true
                  description: "The project id"
                - name: "name"
                  in: path
                  type: string
                  required: true
                  description: "The template name (without version)"
                - name: "offset"
                  in: query
                  type: string
                  required: false
                  description: "offset parameter"
                - name: "limit"
                  in: query
                  type: string
                  required: false
                  description: "limit parameter"
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
        - name: "templates-by-id-by-id-deployments-by-id-migrate"
          path: "/v1/templates/{project_id}/{template_name}/deployments/{deployment_id}/migrate"
          operations:
            - name: "templates_migratedeployment"
              method: POST
              description: "Migrate Deployment to Template Version (Cloud-only)"
              inputParameters:
                - name: "project_id"
                  in: path
                  type: string
                  required: true
                  description: "The project id"
                - name: "template_name"
                  in: path
                  type: string
                  required: true
                  description: "The template name (without version)"
                - name: "deployment_id"
                  in: path
                  type: string
                  required: true
                  description: "The deployment ID to migrate"
                - name: "body"
                  in: body
                  type: object
                  required: true
                  description: "Body"
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
        - name: "templates-by-id-rollback"
          path: "/v1/templates/{template_name}/rollback"
          operations:
            - name: "templates_rollbacktemplatenoproject"
              method: POST
              description: "Rollback Template to Previous Version (Cloud-only)"
              inputParameters:
                - name: "template_name"
                  in: path
                  type: string
                  required: true
                  description: "The template name (without version)"
                - name: "body"
                  in: body
                  type: object
                  required: true
                  description: "Body"
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
        - name: "templates-by-id-by-id-rollback"
          path: "/v1/templates/{project_id}/{template_name}/rollback"
          operations:
            - name: "templates_rollbacktemplate"
              method: POST
              description: "Rollback Template to Previous Version (Cloud-only)"
              inputParameters:
                - name: "project_id"
                  in: path
                  type: string
                  required: true
                  description: "The project id"
                - name: "template_name"
                  in: path
                  type: string
                  required: true
                  description: "The template name (without version)"
                - name: "body"
                  in: body
                  type: object
                  required: true
                  description: "Body"
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
        - name: "templates-by-id-by-id-agent-file"
          path: "/v1/templates/{project_id}/{template_name}/agent-file"
          operations:
            - name: "templates_updatecurrenttemplatefromagentfile"
              method: PUT
              description: "Update Current Template from Agent File (Cloud-only)"
              inputParameters:
                - name: "project_id"
                  in: path
                  type: string
                  required: true
                  description: "The project id"
                - name: "template_name"
                  in: path
                  type: string
                  required: true
                  description: "The template name (without version)"
                - name: "body"
                  in: body
                  type: object
                  required: true
                  description: "Body"
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
        - name: "legacy-templates-by-id-migrates"
          path: "/v1/legacy-templates/{templateId}/migrates"
          operations:
            - name: "templates_legacymigration"
              method: POST
              description: "Migrate Template from Legacy Project (Cloud-only)"
              inputParameters:
                - name: "templateId"
                  in: path
                  type: string
                  required: true
                  description: "The template ID"
                - name: "body"
                  in: body
                  type: object
                  required: true
                  description: "Body"
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."

  exposes:
    - type: rest
      namespace: "letta-templates-rest"
      port: 8080
      description: "REST adapter for Letta API — Templates. One Spectral-compliant resource per consumed operation."
      resources:
        - path: "/v1/templates/{project-id}/{template-version}/agents"
          name: "templates-by-id-by-id-agents"
          description: "REST surface for templates-by-id-by-id-agents."
          operations:
            - method: POST
              name: "templates_createagentsfromtemplate"
              description: "Create Agents from Template"
              call: "letta-templates.templates_createagentsfromtemplate"
              with:
                "project_id": "rest.project_id"
                "template_version": "rest.template_version"
                "body": "rest.body"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: "/v1/templates/{template-version}/agents"
          name: "templates-by-id-agents"
          description: "REST surface for templates-by-id-agents."
          operations:
            - method: POST
              name: "templates_createagentsfromtemplatenoproject"
              description: "Create Agents from Template"
              call: "letta-templates.templates_createagentsfromtemplatenoproject"
              with:
                "template_version": "rest.template_version"
                "body": "rest.body"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: "/v1/templates"
          name: "templates"
          description: "REST surface for templates."
          operations:
            - method: GET
              name: "templates_listtemplates"
              description: "List Templates (Cloud-only)"
              call: "letta-templates.templates_listtemplates"
              with:
                "offset": "rest.offset"
                "exact": "rest.exact"
                "limit": "rest.limit"
                "version": "rest.version"
                "template_id": "rest.template_id"
                "name": "rest.name"
                "search": "rest.search"
                "project_slug": "rest.project_slug"
                "project_id": "rest.project_id"
                "sort_by": "rest.sort_by"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: POST
              name: "templates_createtemplatenoproject"
              description: "Create Template (Cloud-only)"
              call: "letta-templates.templates_createtemplatenoproject"
              with:
                "body": "rest.body"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: "/v1/templates/{template-name}/save"
          name: "templates-by-id-save"
          description: "REST surface for templates-by-id-save."
          operations:
            - method: POST
              name: "templates_savetemplateversionnoproject"
              description: "Save Template Version (Cloud-only)"
              call: "letta-templates.templates_savetemplateversionnoproject"
              with:
                "template_name": "rest.template_name"
                "body": "rest.body"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: "/v1/templates/{project-id}/{template-name}"
          name: "templates-by-id-by-id"
          description: "REST surface for templates-by-id-by-id."
          operations:
            - method: POST
              name: "templates_savetemplateversion"
              description: "Save Template Version (Cloud-only)"
              call: "letta-templates.templates_savetemplateversion"
              with:
                "project_id": "rest.project_id"
                "template_name": "rest.template_name"
                "body": "rest.body"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: DELETE
              name: "templates_deletetemplate"
              description: "Delete Template (Cloud-only)"
              call: "letta-templates.templates_deletetemplate"
              with:
                "project_id": "rest.project_id"
                "template_name": "rest.template_name"
                "body": "rest.body"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: "/v1/templates/{project-id}/{template-version}/snapshot"
          name: "templates-by-id-by-id-snapshot"
          description: "REST surface for templates-by-id-by-id-snapshot."
          operations:
            - method: GET
              name: "templates_gettemplatesnapshot"
              description: "Get Template Snapshot (Cloud-only)"
              call: "letta-templates.templates_gettemplatesnapshot"
              with:
                "project_id": "rest.project_id"
                "template_version": "rest.template_version"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: PUT
              name: "templates_setcurrenttemplatefromsnapshot"
              description: "Set Current Template from Snapshot (Cloud-only)"
              call: "letta-templates.templates_setcurrenttemplatefromsnapshot"
              with:
                "project_id": "rest.project_id"
                "template_version": "rest.template_version"
                "body": "rest.body"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: "/v1/templates/{project-id}/{template-version}/fork"
          name: "templates-by-id-by-id-fork"
          description: "REST surface for templates-by-id-by-id-fork."
          operations:
            - method: POST
              name: "templates_forktemplate"
              description: "Fork Template (Cloud-only)"
              call: "letta-templates.templates_forktemplate"
              with:
                "project_id": "rest.project_id"
                "template_version": "rest.template_version"
                "body": "rest.body"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: "/v1/templates/{project-id}"
          name: "templates-by-id"
          description: "REST surface for templates-by-id."
          operations:
            - method: POST
              name: "templates_createtemplate"
              description: "Create Template (Cloud-only)"
              call: "letta-templates.templates_createtemplate"
              with:
                "project_id": "rest.project_id"
                "body": "rest.body"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: "/v1/templates/{template-name}"
          name: "templates-by-id"
          description: "REST surface for templates-by-id."
          operations:
            - method: DELETE
              name: "templates_deletetemplatenoproject"
              description: "Delete Template (Cloud-only)"
              call: "letta-templates.templates_deletetemplatenoproject"
              with:
                "template_name": "rest.template_name"
                "body": "rest.body"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: PATCH
              name: "templates_updatecurrenttemplatefromagentfilenoproject"
              description: "Update Current Template from Agent File (Cloud-only)"
              call: "letta-templates.templates_updatecurrenttemplatefromagentfilenoproject"
              with:
                "template_name": "rest.template_name"
                "body": "rest.body"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: "/v1/templates/{project-id}/{template-name}/name"
          name: "templates-by-id-by-id-name"
          description: "REST surface for templates-by-id-by-id-name."
          operations:
            - method: PATCH
              name: "templates_renametemplate"
              description: "Rename Template (Cloud-only)"
              call: "letta-templates.templates_renametemplate"
              with:
                "project_id": "rest.project_id"
                "template_name": "rest.template_name"
                "body": "rest.body"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: "/v1/templates/{project-id}/{template-name}/description"
          name: "templates-by-id-by-id-description"
          description: "REST surface for templates-by-id-by-id-description."
          operations:
            - method: PATCH
              name: "templates_updatetemplatedescription"
              description: "Update Template Description (Cloud-only)"
              call: "letta-templates.templates_updatetemplatedescription"
              with:
                "project_id": "rest.project_id"
                "template_name": "rest.template_name"
                "body": "rest.body"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: "/v1/templates/{project-id}/{name}/versions"
          name: "templates-by-id-by-id-versions"
          description: "REST surface for templates-by-id-by-id-versions."
          operations:
            - method: GET
              name: "templates_listtemplateversions"
              description: "List Template Versions (Cloud-only)"
              call: "letta-templates.templates_listtemplateversions"
              with:
                "project_id": "rest.project_id"
                "name": "rest.name"
                "offset": "rest.offset"
                "limit": "rest.limit"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: "/v1/templates/{project-id}/{template-name}/deployments/{deployment-id}/migrate"
          name: "templates-by-id-by-id-deployments-by-id-migrate"
          description: "REST surface for templates-by-id-by-id-deployments-by-id-migrate."
          operations:
            - method: POST
              name: "templates_migratedeployment"
              description: "Migrate Deployment to Template Version (Cloud-only)"
              call: "letta-templates.templates_migratedeployment"
              with:
                "project_id": "rest.project_id"
                "template_name": "rest.template_name"
                "deployment_id": "rest.deployment_id"
                "body": "rest.body"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: "/v1/templates/{template-name}/rollback"
          name: "templates-by-id-rollback"
          description: "REST surface for templates-by-id-r

# --- truncated at 32 KB (45 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/letta/refs/heads/main/capabilities/letta-templates.yaml