ctlsurf

ctlsurf Blocks API

The blocks API from ctlsurf — 11 operation(s) for blocks.

GitHub OpenAPI

Operations 14

GET /api/blocks/search Search Blocks #
GET /api/blocks/page/{page_id} List Blocks For Page #
POST /api/blocks/page/{page_id} Create Block #
GET /api/blocks/page/{page_id}/summary List Block Summaries #
GET /api/blocks/{block_id} Get Block #
PUT /api/blocks/{block_id} Update Block #
DELETE /api/blocks/{block_id} Delete Block #
GET /api/blocks/{block_id}/slice Get Block Slice #
GET /api/blocks/{block_id}/history Get Block History #
POST /api/blocks/{block_id}/restore/{version_number} Restore Block Version #
POST /api/blocks/page/{page_id}/reorder Reorder Blocks #
POST /api/blocks/{block_id}/convert Convert Block #
POST /api/blocks/page/{page_id}/batch Create Blocks Batch #
POST /api/blocks/move Move Blocks #

Documentation

📖
Documentation
https://ctlsurf.com/docs

Specifications

⚙
OpenAPI
https://artifacts.apis.io/ctlsurf-com/openapi/ctlsurf-com-blocks-api-openapi.yml

Schemas & Data

📊
JSONSchema
https://artifacts.apis.io/ctlsurf-com/json-schema/ctlsurf-com-block-content-slice-schema.json
📊
JSONSchema
https://artifacts.apis.io/ctlsurf-com/json-schema/ctlsurf-com-block-response-schema.json
📊
JSONSchema
https://artifacts.apis.io/ctlsurf-com/json-schema/ctlsurf-com-block-summary-schema.json
📊
JSONSchema
https://artifacts.apis.io/ctlsurf-com/json-schema/ctlsurf-com-block-version-response-schema.json
📊
JSONSchema
https://artifacts.apis.io/ctlsurf-com/json-schema/ctlsurf-com-block-move-schema.json
📊
JSONSchema
https://artifacts.apis.io/ctlsurf-com/json-schema/ctlsurf-com-block-batch-create-schema.json

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.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/ctlsurf-com:ctlsurf-com-blocks-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.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

ctlsurf-com-blocks-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: Ctlsurf Com Blocks API
  version: 0.1.0
  description: 'Operations tagged blocks 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: Blocks
paths:
  /api/blocks/search:
    get:
      tags:
      - Blocks
      summary: Search Blocks
      description: 'Search over block content using PostgreSQL full-text search with trigram fuzzy matching fallback.

        Returns snippets only; fetch full text via /blocks/{block_id}/slice.


        Features:

        - Full-text search with stemming (run/running/ran all match)

        - Trigram fuzzy matching for typo tolerance (threshold 0.3)

        - Results ranked by relevance'
      operationId: search_blocks_api_blocks_search_get
      security:
      - HTTPBearer: []
      parameters:
      - name: q
        in: query
        required: true
        schema:
          type: string
          title: Q
      - name: page_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Page Id
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 20
          title: Limit
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          default: 0
          title: Offset
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlockSearchResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/blocks/page/{page_id}:
    get:
      tags:
      - Blocks
      summary: List Blocks For Page
      operationId: list_blocks_for_page_api_blocks_page__page_id__get
      security:
      - HTTPBearer: []
      parameters:
      - name: page_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Page Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BlockResponse'
                title: Response List Blocks For Page Api Blocks Page  Page Id  Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    post:
      tags:
      - Blocks
      summary: Create Block
      operationId: create_block_api_blocks_page__page_id__post
      security:
      - HTTPBearer: []
      parameters:
      - name: page_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Page Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BlockCreate'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlockResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/blocks/page/{page_id}/summary:
    get:
      tags:
      - Blocks
      summary: List Block Summaries
      description: Lightweight block listing without heavy props; includes size hints.
      operationId: list_block_summaries_api_blocks_page__page_id__summary_get
      security:
      - HTTPBearer: []
      parameters:
      - name: page_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Page Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BlockSummary'
                title: Response List Block Summaries Api Blocks Page  Page Id  Summary Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/blocks/{block_id}:
    get:
      tags:
      - Blocks
      summary: Get Block
      operationId: get_block_api_blocks__block_id__get
      security:
      - HTTPBearer: []
      parameters:
      - name: block_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Block Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlockResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    put:
      tags:
      - Blocks
      summary: Update Block
      operationId: update_block_api_blocks__block_id__put
      security:
      - HTTPBearer: []
      parameters:
      - name: block_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Block Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BlockUpdate'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlockResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Blocks
      summary: Delete Block
      operationId: delete_block_api_blocks__block_id__delete
      security:
      - HTTPBearer: []
      parameters:
      - name: block_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Block Id
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/blocks/{block_id}/slice:
    get:
      tags:
      - Blocks
      summary: Get Block Slice
      description: Fetch a slice of a block's content for large payloads.
      operationId: get_block_slice_api_blocks__block_id__slice_get
      security:
      - HTTPBearer: []
      parameters:
      - name: block_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Block Id
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          default: 0
          title: Offset
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 8000
          title: Limit
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlockContentSlice'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/blocks/{block_id}/history:
    get:
      tags:
      - Blocks
      summary: Get Block History
      description: Get version history for a block. Requires Pro tier.
      operationId: get_block_history_api_blocks__block_id__history_get
      security:
      - HTTPBearer: []
      parameters:
      - name: block_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Block Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BlockVersionResponse'
                title: Response Get Block History Api Blocks  Block Id  History Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/blocks/{block_id}/restore/{version_number}:
    post:
      tags:
      - Blocks
      summary: Restore Block Version
      description: Restore a block to a specific version. Requires Pro tier.
      operationId: restore_block_version_api_blocks__block_id__restore__version_number__post
      security:
      - HTTPBearer: []
      parameters:
      - name: block_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Block Id
      - name: version_number
        in: path
        required: true
        schema:
          type: integer
          title: Version Number
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlockResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/blocks/page/{page_id}/reorder:
    post:
      tags:
      - Blocks
      summary: Reorder Blocks
      operationId: reorder_blocks_api_blocks_page__page_id__reorder_post
      security:
      - HTTPBearer: []
      parameters:
      - name: page_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Page Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BlockReorder'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BlockResponse'
                title: Response Reorder Blocks Api Blocks Page  Page Id  Reorder Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/blocks/{block_id}/convert:
    post:
      tags:
      - Blocks
      summary: Convert Block
      description: Turn a block into another type in place, keeping its ID, position and history.
      operationId: convert_block_api_blocks__block_id__convert_post
      security:
      - HTTPBearer: []
      parameters:
      - name: block_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Block Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BlockConvert'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlockResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/blocks/page/{page_id}/batch:
    post:
      tags:
      - Blocks
      summary: Create Blocks Batch
      description: Insert blocks after a block in one step (paste, duplicate, insert between).
      operationId: create_blocks_batch_api_blocks_page__page_id__batch_post
      security:
      - HTTPBearer: []
      parameters:
      - name: page_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Page Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BlockBatchCreate'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BlockResponse'
                title: Response Create Blocks Batch Api Blocks Page  Page Id  Batch Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/blocks/move:
    post:
      tags:
      - Blocks
      summary: Move Blocks
      description: 'Move blocks to a position on the same or another page.


        Blocks keep their ID, history, files, diagrams and datastore rows. Used for

        drag-to-reorder and for paste after cut. Returns the target page''s blocks.'
      operationId: move_blocks_api_blocks_move_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BlockMove'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/BlockResponse'
                type: array
                title: Response Move Blocks Api Blocks Move Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
components:
  schemas:
    BlockBatchItem:
      properties:
        type:
          $ref: '#/components/schemas/BlockType'
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
        props:
          additionalProperties: true
          type: object
          title: Props
          default: {}
      type: object
      required:
      - type
      title: BlockBatchItem
    BlockUpdate:
      properties:
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
        props:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Props
        order:
          anyOf:
          - type: integer
          - type: 'null'
          title: Order
      type: object
      title: BlockUpdate
    BlockCreate:
      properties:
        type:
          $ref: '#/components/schemas/BlockType'
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
        props:
          additionalProperties: true
          type: object
          title: Props
          default: {}
        order:
          anyOf:
          - type: integer
          - type: 'null'
          title: Order
      type: object
      required:
      - type
      title: BlockCreate
    BlockReorder:
      properties:
        block_ids:
          items:
            type: string
            format: uuid
          type: array
          title: Block Ids
      type: object
      required:
      - block_ids
      title: BlockReorder
    BlockBatchCreate:
      properties:
        blocks:
          items:
            $ref: '#/components/schemas/BlockBatchItem'
          type: array
          maxItems: 200
          minItems: 1
          title: Blocks
        after_block_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: After Block Id
        at_start:
          type: boolean
          title: At Start
          default: false
      type: object
      required:
      - blocks
      title: BlockBatchCreate
      description: 'Insert blocks in order after a block (default: at the end of the page).'
    BlockSearchResult:
      properties:
        block_id:
          type: string
          format: uuid
          title: Block Id
        page_id:
          type: string
          format: uuid
          title: Page Id
        page_title:
          anyOf:
          - type: string
          - type: 'null'
          title: Page Title
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
        type:
          $ref: '#/components/schemas/BlockType'
        match_start:
          type: integer
          title: Match Start
        match_end:
          type: integer
          title: Match End
        snippet:
          type: string
          title: Snippet
        size_bytes:
          type: integer
          title: Size Bytes
        content_type:
          type: string
          title: Content Type
      type: object
      required:
      - block_id
      - page_id
      - page_title
      - title
      - type
      - match_start
      - match_end
      - snippet
      - size_bytes
      - content_type
      title: BlockSearchResult
    BlockVersionResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        block_id:
          type: string
          format: uuid
          title: Block Id
        version_number:
          type: integer
          title: Version Number
        type:
          $ref: '#/components/schemas/BlockType'
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
        props:
          additionalProperties: true
          type: object
          title: Props
        created_at:
          type: string
          format: date-time
          title: Created At
      type: object
      required:
      - id
      - block_id
      - version_number
      - type
      - props
      - created_at
      title: BlockVersionResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    BlockResponse:
      properties:
        type:
          $ref: '#/components/schemas/BlockType'
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
        props:
          additionalProperties: true
          type: object
          title: Props
          default: {}
        id:
          type: string
          format: uuid
          title: Id
        page_id:
          type: string
          format: uuid
          title: Page Id
        order:
          type: integer
          title: Order
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
      type: object
      required:
      - type
      - id
      - page_id
      - order
      - created_at
      - updated_at
      title: BlockResponse
    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
    BlockMove:
      properties:
        block_ids:
          items:
            type: string
            format: uuid
          type: array
          maxItems: 200
          minItems: 1
          title: Block Ids
        page_id:
          type: string
          format: uuid
          title: Page Id
        after_block_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: After Block Id
        at_start:
          type: boolean
          title: At Start
          default: false
      type: object
      required:
      - block_ids
      - page_id
      title: BlockMove
      description: Move blocks, in this order, to a page (same or another) after a block.
    BlockConvert:
      properties:
        type:
          $ref: '#/components/schemas/BlockType'
        props:
          additionalProperties: true
          type: object
          title: Props
      type: object
      required:
      - type
      - props
      title: BlockConvert
      description: 'Turn a block into another type in place: same ID, page and position.'
    BlockType:
      type: string
      enum:
      - text
      - checklist
      - table
      - react_flow
      - agent_control
      - tree
      - ctlsurf_task
      - page_summary
      - file
      - mindmap
      - datastore
      - state
      - log
      - presentation
      title: BlockType
    BlockSearchResponse:
      properties:
        results:
          items:
            $ref: '#/components/schemas/BlockSearchResult'
          type: array
          title: Results
        total:
          type: integer
          title: Total
        limit:
          type: integer
          title: Limit
        offset:
          type: integer
          title: Offset
        has_more:
          type: boolean
          title: Has More
      type: object
      required:
      - results
      - total
      - limit
      - offset
      - has_more
      title: BlockSearchResponse
    BlockSummary:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        page_id:
          type: string
          format: uuid
          title: Page Id
        type:
          $ref: '#/components/schemas/BlockType'
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
        order:
          type: integer
          title: Order
        size_bytes:
          type: integer
          title: Size Bytes
        content_type:
          type: string
          title: Content Type
        has_large_content:
          type: boolean
          title: Has Large Content
      type: object
      required:
      - id
      - page_id
      - type
      - title
      - order
      - size_bytes
      - content_type
      - has_large_content
      title: BlockSummary
    BlockContentSlice:
      properties:
        block_id:
          type: string
          format: uuid
          title: Block Id
        page_id:
          type: string
          format: uuid
          title: Page Id
        type:
          $ref: '#/components/schemas/BlockType'
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
        offset:
          type: integer
          title: Offset
        limit:
          type: integer
          title: Limit
        total_size:
          type: integer
          title: Total Size
        has_more:
          type: boolean
          title: Has More
        next_offset:
          anyOf:
          - type: integer
          - type: 'null'
          title: Next Offset
        content_type:
          type: string
          title: Content Type
        content_slice:
          type: string
          title: Content Slice
      type: object
      required:
      - block_id
      - page_id
      - type
      - title
      - offset
      - limit
      - total_size
      - has_more
      - next_offset
      - content_type
      - content_slice
      title: BlockContentSlice
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer
x-refined-from:
- ctlsurf-com-openapi.json
- ctlsurf-com-openapi.yml