Convoy API — Sources

naftiko: 1.0.0-alpha2
info:
  label: "Convoy API \u2014 Sources"
  description: "Convoy webhooks gateway \u2014 Sources. 5 operations. Lead operation: List all sources. Self-contained Naftiko\
    \ capability covering one Convoy business surface."
  tags:
  - Convoy
  - Webhooks
  - Sources
  created: '2026-05-22'
  modified: '2026-05-22'
binds:
- namespace: env
  keys:
    CONVOY_API_KEY: CONVOY_API_KEY
capability:
  consumes:
  - type: http
    namespace: convoy-sources
    baseUri: https://us.getconvoy.cloud/api
    description: "Convoy API \u2014 Sources business capability. Self-contained, no shared references."
    authentication:
      type: bearer
      token: '{{env.CONVOY_API_KEY}}'
    resources:
    - name: v1-projects-project-id-sources
      path: /v1/projects/{projectID}/sources
      operations:
      - name: LoadSourcesPaged
        method: GET
        description: List all sources
        inputParameters:
        - name: projectID
          in: path
          type: string
          required: true
          description: Project ID
        - name: direction
          in: query
          type: string
          required: false
          description: query parameter direction
        - name: next_page_cursor
          in: query
          type: string
          required: false
          description: A pagination cursor to fetch the next page of a list
        - name: perPage
          in: query
          type: integer
          required: false
          description: The number of items to return per page
        - name: prev_page_cursor
          in: query
          type: string
          required: false
          description: A pagination cursor to fetch the previous page of a list
        - name: provider
          in: query
          type: string
          required: false
          description: The custom source provider e.g. twitter, shopify
        - name: sort
          in: query
          type: string
          required: false
          description: Sort order, values are `ASC` or `DESC`, defaults to `DESC`
        - name: type
          in: query
          type: string
          required: false
          description: The source type e.g. http, pub_sub
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: CreateSource
        method: POST
        description: Create a source
        inputParameters:
        - name: projectID
          in: path
          type: string
          required: true
          description: Project ID
        - name: body
          in: body
          type: object
          required: true
          description: Request body payload.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: v1-projects-project-id-sources-source-id
      path: /v1/projects/{projectID}/sources/{sourceID}
      operations:
      - name: DeleteSource
        method: DELETE
        description: Delete a source
        inputParameters:
        - name: projectID
          in: path
          type: string
          required: true
          description: Project ID
        - name: sourceID
          in: path
          type: string
          required: true
          description: source id
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: GetSource
        method: GET
        description: Retrieve a source
        inputParameters:
        - name: projectID
          in: path
          type: string
          required: true
          description: Project ID
        - name: sourceID
          in: path
          type: string
          required: true
          description: Source ID
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: UpdateSource
        method: PUT
        description: Update a source
        inputParameters:
        - name: projectID
          in: path
          type: string
          required: true
          description: Project ID
        - name: sourceID
          in: path
          type: string
          required: true
          description: source id
        - name: body
          in: body
          type: object
          required: true
          description: Request body payload.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  exposes:
  - type: rest
    namespace: convoy-sources-rest
    port: 8080
    description: "REST adapter for Convoy API \u2014 Sources. One Spectral-compliant resource per consumed operation, prefixed\
      \ with /v1."
    resources:
    - path: /v1/projects/{project-id}/sources
      name: v1-projects-project-id-sources
      description: REST surface for /v1/projects/{project-id}/sources.
      operations:
      - method: GET
        name: LoadSourcesPaged
        description: List all sources
        call: convoy-sources.LoadSourcesPaged
        with:
          projectID: rest.projectID
          direction: rest.direction
          next_page_cursor: rest.next_page_cursor
          perPage: rest.perPage
          prev_page_cursor: rest.prev_page_cursor
          provider: rest.provider
          sort: rest.sort
          type: rest.type
        outputParameters:
        - type: object
          mapping: $.
      - method: POST
        name: CreateSource
        description: Create a source
        call: convoy-sources.CreateSource
        with:
          projectID: rest.projectID
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/projects/{project-id}/sources/{source-id}
      name: v1-projects-project-id-sources-source-id
      description: REST surface for /v1/projects/{project-id}/sources/{source-id}.
      operations:
      - method: DELETE
        name: DeleteSource
        description: Delete a source
        call: convoy-sources.DeleteSource
        with:
          projectID: rest.projectID
          sourceID: rest.sourceID
        outputParameters:
        - type: object
          mapping: $.
      - method: GET
        name: GetSource
        description: Retrieve a source
        call: convoy-sources.GetSource
        with:
          projectID: rest.projectID
          sourceID: rest.sourceID
        outputParameters:
        - type: object
          mapping: $.
      - method: PUT
        name: UpdateSource
        description: Update a source
        call: convoy-sources.UpdateSource
        with:
          projectID: rest.projectID
          sourceID: rest.sourceID
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: convoy-sources-mcp
    port: 9090
    transport: http
    description: "MCP adapter for Convoy API \u2014 Sources. One tool per consumed operation, routed inline through this capability's\
      \ consumes block."
    tools:
    - name: list-sources
      description: List all sources
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: convoy-sources.LoadSourcesPaged
      with:
        projectID: tools.projectID
        direction: tools.direction
        next_page_cursor: tools.next_page_cursor
        perPage: tools.perPage
        prev_page_cursor: tools.prev_page_cursor
        provider: tools.provider
        sort: tools.sort
        type: tools.type
      outputParameters:
      - type: object
        mapping: $.
    - name: create-source
      description: Create a source
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: convoy-sources.CreateSource
      with:
        projectID: tools.projectID
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: delete-source
      description: Delete a source
      hints:
        readOnly: false
        destructive: true
        idempotent: true
      call: convoy-sources.DeleteSource
      with:
        projectID: tools.projectID
        sourceID: tools.sourceID
      outputParameters:
      - type: object
        mapping: $.
    - name: retrieve-source
      description: Retrieve a source
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: convoy-sources.GetSource
      with:
        projectID: tools.projectID
        sourceID: tools.sourceID
      outputParameters:
      - type: object
        mapping: $.
    - name: update-source
      description: Update a source
      hints:
        readOnly: false
        destructive: false
        idempotent: true
      call: convoy-sources.UpdateSource
      with:
        projectID: tools.projectID
        sourceID: tools.sourceID
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.