ctlsurf Folders API
The folders API from ctlsurf — 9 operation(s) for folders.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/ctlsurf-com:ctlsurf-com-folders-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Ctlsurf Com Folders API
version: 0.1.0
description: 'Operations tagged folders across 2 of this provider''s published API definitions: ctlsurf-com-openapi.json, ctlsurf-com-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://app.ctlsurf.com
description: ctlsurf application host (documented MCP endpoint https://app.ctlsurf.com/api/mcp; spec served at /openapi.json)
tags:
- name: Folders
paths:
/api/folders/find-by-path:
post:
tags:
- Folders
summary: Find Folder By Path
description: Find a folder by its root_path.
operationId: find_folder_by_path_api_folders_find_by_path_post
requestBody:
content:
application/json:
schema:
additionalProperties: true
type: object
title: Body
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- HTTPBearer: []
/api/folders:
get:
tags:
- Folders
summary: List Folders
description: List all folders for the current user, optionally with their pages.
operationId: list_folders_api_folders_get
security:
- HTTPBearer: []
parameters:
- name: include_archived
in: query
required: false
schema:
type: boolean
description: Include archived folders
default: false
title: Include Archived
description: Include archived folders
- name: slim
in: query
required: false
schema:
type: boolean
description: Return folders without pages (much faster)
default: false
title: Slim
description: Return folders without pages (much faster)
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
post:
tags:
- Folders
summary: Create Folder
description: Create a new folder.
operationId: create_folder_api_folders_post
security:
- HTTPBearer: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/FolderCreate'
responses:
'201':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/FolderResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/folders/search:
get:
tags:
- Folders
summary: Search Folder
description: 'Find a folder by path, git URL, or name.
Args:
query: The search value
type: One of:
- ''path'': Search by local filesystem root_path
- ''url'': Search by git remote URL (e.g., https://github.com/user/repo)
- ''name'': Search by folder name (partial match)'
operationId: search_folder_api_folders_search_get
security:
- HTTPBearer: []
parameters:
- name: query
in: query
required: true
schema:
type: string
description: The search value
title: Query
description: The search value
- name: type
in: query
required: true
schema:
type: string
description: 'Search type: ''path'' (local filesystem), ''url'' (git remote URL), or ''name'' (folder name text search)'
title: Type
description: 'Search type: ''path'' (local filesystem), ''url'' (git remote URL), or ''name'' (folder name text search)'
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/folders/by-path:
get:
tags:
- Folders
summary: Get Folder By Path
description: Find a folder by its root_path (legacy endpoint, use /search instead).
operationId: get_folder_by_path_api_folders_by_path_get
security:
- HTTPBearer: []
parameters:
- name: root_path
in: query
required: true
schema:
type: string
description: The root path to search for
title: Root Path
description: The root path to search for
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/folders/groups/archive:
post:
tags:
- Folders
summary: Archive Group
description: 'Archive every active project in a group. Nothing is deleted; the projects keep
their group so the whole group can be restored together.'
operationId: archive_group_api_folders_groups_archive_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/GroupAction'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- HTTPBearer: []
/api/folders/groups/restore:
post:
tags:
- Folders
summary: Restore Group
description: Restore every archived project in a group.
operationId: restore_group_api_folders_groups_restore_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/GroupAction'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- HTTPBearer: []
/api/folders/{folder_id}:
get:
tags:
- Folders
summary: Get Folder
description: Get a folder with its pages.
operationId: get_folder_api_folders__folder_id__get
security:
- HTTPBearer: []
parameters:
- name: folder_id
in: path
required: true
schema:
type: string
format: uuid
title: Folder Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/FolderWithPages'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
put:
tags:
- Folders
summary: Update Folder
description: Update a folder.
operationId: update_folder_api_folders__folder_id__put
security:
- HTTPBearer: []
parameters:
- name: folder_id
in: path
required: true
schema:
type: string
format: uuid
title: Folder Id
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/FolderUpdate'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/FolderResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
delete:
tags:
- Folders
summary: Delete Folder
description: Delete a folder. Pages in the folder will be moved to root (no folder).
operationId: delete_folder_api_folders__folder_id__delete
security:
- HTTPBearer: []
parameters:
- name: folder_id
in: path
required: true
schema:
type: string
format: uuid
title: Folder Id
responses:
'204':
description: Successful Response
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/folders/{folder_id}/archive:
post:
tags:
- Folders
summary: Archive Folder
description: Archive a folder. Archived folders don't count toward the project quota.
operationId: archive_folder_api_folders__folder_id__archive_post
security:
- HTTPBearer: []
parameters:
- name: folder_id
in: path
required: true
schema:
type: string
format: uuid
title: Folder Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/FolderResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/folders/{folder_id}/restore:
post:
tags:
- Folders
summary: Restore Folder
description: Restore an archived folder.
operationId: restore_folder_api_folders__folder_id__restore_post
security:
- HTTPBearer: []
parameters:
- name: folder_id
in: path
required: true
schema:
type: string
format: uuid
title: Folder Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/FolderResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
components:
schemas:
OrganizationPlacementReceipt:
properties:
project_root_id:
type: string
format: uuid
title: Project Root Id
binding_revision:
type: integer
title: Binding Revision
template_id:
type: string
format: uuid
title: Template Id
template_version:
type: integer
title: Template Version
template_name:
type: string
title: Template Name
mode:
type: string
enum:
- section
- user_override
title: Mode
section_key:
anyOf:
- type: string
- type: 'null'
title: Section Key
section_path:
items:
type: string
type: array
title: Section Path
override_reason:
anyOf:
- type: string
- type: 'null'
title: Override Reason
destination_parent_id:
type: string
format: uuid
title: Destination Parent Id
semantic_review:
type: string
const: not_performed
title: Semantic Review
default: not_performed
additionalProperties: false
type: object
required:
- project_root_id
- binding_revision
- template_id
- template_version
- template_name
- mode
- destination_parent_id
title: OrganizationPlacementReceipt
GroupAction:
properties:
group:
type: string
maxLength: 255
minLength: 1
title: Group
type: object
required:
- group
title: GroupAction
FolderWithPages:
properties:
name:
type: string
title: Name
root_path:
anyOf:
- type: string
- type: 'null'
title: Root Path
git_remote:
anyOf:
- type: string
- type: 'null'
title: Git Remote
hostname:
anyOf:
- type: string
- type: 'null'
title: Hostname
group:
anyOf:
- type: string
- type: 'null'
title: Group
id:
type: string
format: uuid
title: Id
user_id:
type: string
format: uuid
title: User Id
chat_logging_enabled:
type: boolean
title: Chat Logging Enabled
default: true
archived_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Archived At
created_at:
type: string
format: date-time
title: Created At
updated_at:
type: string
format: date-time
title: Updated At
pages:
items:
$ref: '#/components/schemas/PageTreeNode'
type: array
title: Pages
default: []
type: object
required:
- name
- id
- user_id
- created_at
- updated_at
title: FolderWithPages
FolderResponse:
properties:
name:
type: string
title: Name
root_path:
anyOf:
- type: string
- type: 'null'
title: Root Path
git_remote:
anyOf:
- type: string
- type: 'null'
title: Git Remote
hostname:
anyOf:
- type: string
- type: 'null'
title: Hostname
group:
anyOf:
- type: string
- type: 'null'
title: Group
id:
type: string
format: uuid
title: Id
user_id:
type: string
format: uuid
title: User Id
chat_logging_enabled:
type: boolean
title: Chat Logging Enabled
default: true
archived_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Archived At
created_at:
type: string
format: date-time
title: Created At
updated_at:
type: string
format: date-time
title: Updated At
type: object
required:
- name
- id
- user_id
- created_at
- updated_at
title: FolderResponse
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
type: object
required:
- loc
- msg
- type
title: ValidationError
FolderUpdate:
properties:
name:
anyOf:
- type: string
- type: 'null'
title: Name
root_path:
anyOf:
- type: string
- type: 'null'
title: Root Path
git_remote:
anyOf:
- type: string
- type: 'null'
title: Git Remote
hostname:
anyOf:
- type: string
- type: 'null'
title: Hostname
group:
anyOf:
- type: string
- type: 'null'
title: Group
chat_logging_enabled:
anyOf:
- type: boolean
- type: 'null'
title: Chat Logging Enabled
type: object
title: FolderUpdate
FolderCreate:
properties:
name:
type: string
title: Name
root_path:
anyOf:
- type: string
- type: 'null'
title: Root Path
git_remote:
anyOf:
- type: string
- type: 'null'
title: Git Remote
hostname:
anyOf:
- type: string
- type: 'null'
title: Hostname
group:
anyOf:
- type: string
- type: 'null'
title: Group
type: object
required:
- name
title: FolderCreate
PageTreeNode:
properties:
title:
type: string
title: Title
default: Untitled
root_path:
anyOf:
- type: string
- type: 'null'
title: Root Path
repo_url:
anyOf:
- type: string
- type: 'null'
title: Repo Url
tags:
items:
type: string
type: array
title: Tags
default: []
type:
type: string
title: Type
default: page
id:
type: string
format: uuid
title: Id
parent_id:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Parent Id
folder_id:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Folder Id
user_id:
type: string
format: uuid
title: User Id
order:
type: integer
title: Order
default: 0
created_at:
type: string
format: date-time
title: Created At
updated_at:
type: string
format: date-time
title: Updated At
deleted_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Deleted At
is_project:
type: boolean
title: Is Project
default: false
is_private:
type: boolean
title: Is Private
default: false
is_private_inherited:
type: boolean
title: Is Private Inherited
default: false
organization_placement:
anyOf:
- $ref: '#/components/schemas/OrganizationPlacementReceipt'
- type: 'null'
children:
items:
$ref: '#/components/schemas/PageTreeNode'
type: array
title: Children
default: []
type: object
required:
- id
- user_id
- created_at
- updated_at
title: PageTreeNode
securitySchemes:
HTTPBearer:
type: http
scheme: bearer
x-refined-from:
- ctlsurf-com-openapi.json
- ctlsurf-com-openapi.yml