Suger API — Contact

naftiko: 1.0.0-alpha2
info:
  label: Suger API — Contact
  description: 'Suger API — Contact. 9 operations. Lead operation: List Contacts By Organization. Self-contained Naftiko capability
    covering one Suger business surface.'
  tags:
  - Suger
  - Contact
  created: '2026-05-19'
  modified: '2026-05-19'
binds:
- namespace: env
  keys:
    SUGER_API_KEY: SUGER_API_KEY
capability:
  consumes:
  - type: http
    namespace: suger-contact
    baseUri: https://api.suger.cloud
    description: Suger API — Contact business capability. Self-contained, no shared references.
    resources:
    - name: org-orgId-contact
      path: /org/{orgId}/contact
      operations:
      - name: listcontactsbyorganization
        method: GET
        description: List Contacts By Organization
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: orgId
          in: path
          type: string
          description: Organization ID
          required: true
        - name: limit
          in: query
          type: integer
          description: List pagination size, default 1000, max value is 1000
        - name: offset
          in: query
          type: integer
          description: List pagination offset, default 0
      - name: createcontact
        method: POST
        description: Create Contact
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: orgId
          in: path
          type: string
          description: Organization ID
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: org-orgId-contact-batch
      path: /org/{orgId}/contact/batch
      operations:
      - name: batchcreatecontacts
        method: POST
        description: Batch Create Contacts
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: orgId
          in: path
          type: string
          description: Organization ID
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: org-orgId-contact-contactId
      path: /org/{orgId}/contact/{contactId}
      operations:
      - name: getcontact
        method: GET
        description: Get Contact
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: orgId
          in: path
          type: string
          description: Organization ID
          required: true
        - name: contactId
          in: path
          type: string
          description: Contact ID
          required: true
      - name: updatecontact
        method: PATCH
        description: Update Contact
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: orgId
          in: path
          type: string
          description: Organization ID
          required: true
        - name: contactId
          in: path
          type: string
          description: Contact ID
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: org-orgId-contact-contactId-buyer-buyerId
      path: /org/{orgId}/contact/{contactId}/buyer/{buyerId}
      operations:
      - name: removecontactfrombuyer
        method: DELETE
        description: Remove Contact From Buyer
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: orgId
          in: path
          type: string
          description: Organization ID
          required: true
        - name: buyerId
          in: path
          type: string
          description: Buyer ID
          required: true
        - name: contactId
          in: path
          type: string
          description: Contact ID
          required: true
      - name: addcontacttobuyer
        method: POST
        description: Add Contact To Buyer
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: orgId
          in: path
          type: string
          description: Organization ID
          required: true
        - name: buyerId
          in: path
          type: string
          description: Buyer ID
          required: true
        - name: contactId
          in: path
          type: string
          description: Contact ID
          required: true
    - name: org-orgId-contact-contactId-offer-offerId
      path: /org/{orgId}/contact/{contactId}/offer/{offerId}
      operations:
      - name: removecontactfromoffer
        method: DELETE
        description: Remove Contact From Offer
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: orgId
          in: path
          type: string
          description: Organization ID
          required: true
        - name: contactId
          in: path
          type: string
          description: Contact ID
          required: true
        - name: offerId
          in: path
          type: string
          description: Offer ID
          required: true
      - name: addcontacttooffer
        method: POST
        description: Add Contact To Offer
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: orgId
          in: path
          type: string
          description: Organization ID
          required: true
        - name: contactId
          in: path
          type: string
          description: Contact ID
          required: true
        - name: offerId
          in: path
          type: string
          description: Offer ID
          required: true
    authentication:
      type: apikey
      key: Authorization
      value: '{{env.SUGER_API_KEY}}'
      placement: header
  exposes:
  - type: rest
    namespace: suger-contact-rest
    port: 8080
    description: REST adapter for Suger API — Contact. One Spectral-compliant resource per consumed operation, prefixed with
      /v1.
    resources:
    - path: /v1/org/{orgid}/contact
      name: org-orgid-contact
      description: REST surface for org-orgId-contact.
      operations:
      - method: GET
        name: listcontactsbyorganization
        description: List Contacts By Organization
        call: suger-contact.listcontactsbyorganization
        with:
          orgId: rest.orgId
          limit: rest.limit
          offset: rest.offset
        outputParameters:
        - type: object
          mapping: $.
      - method: POST
        name: createcontact
        description: Create Contact
        call: suger-contact.createcontact
        with:
          orgId: rest.orgId
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/org/{orgid}/contact/batch
      name: org-orgid-contact-batch
      description: REST surface for org-orgId-contact-batch.
      operations:
      - method: POST
        name: batchcreatecontacts
        description: Batch Create Contacts
        call: suger-contact.batchcreatecontacts
        with:
          orgId: rest.orgId
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/org/{orgid}/contact/{contactid}
      name: org-orgid-contact-contactid
      description: REST surface for org-orgId-contact-contactId.
      operations:
      - method: GET
        name: getcontact
        description: Get Contact
        call: suger-contact.getcontact
        with:
          orgId: rest.orgId
          contactId: rest.contactId
        outputParameters:
        - type: object
          mapping: $.
      - method: PATCH
        name: updatecontact
        description: Update Contact
        call: suger-contact.updatecontact
        with:
          orgId: rest.orgId
          contactId: rest.contactId
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/org/{orgid}/contact/{contactid}/buyer/{buyerid}
      name: org-orgid-contact-contactid-buyer-buyerid
      description: REST surface for org-orgId-contact-contactId-buyer-buyerId.
      operations:
      - method: DELETE
        name: removecontactfrombuyer
        description: Remove Contact From Buyer
        call: suger-contact.removecontactfrombuyer
        with:
          orgId: rest.orgId
          buyerId: rest.buyerId
          contactId: rest.contactId
        outputParameters:
        - type: object
          mapping: $.
      - method: POST
        name: addcontacttobuyer
        description: Add Contact To Buyer
        call: suger-contact.addcontacttobuyer
        with:
          orgId: rest.orgId
          buyerId: rest.buyerId
          contactId: rest.contactId
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/org/{orgid}/contact/{contactid}/offer/{offerid}
      name: org-orgid-contact-contactid-offer-offerid
      description: REST surface for org-orgId-contact-contactId-offer-offerId.
      operations:
      - method: DELETE
        name: removecontactfromoffer
        description: Remove Contact From Offer
        call: suger-contact.removecontactfromoffer
        with:
          orgId: rest.orgId
          contactId: rest.contactId
          offerId: rest.offerId
        outputParameters:
        - type: object
          mapping: $.
      - method: POST
        name: addcontacttooffer
        description: Add Contact To Offer
        call: suger-contact.addcontacttooffer
        with:
          orgId: rest.orgId
          contactId: rest.contactId
          offerId: rest.offerId
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: suger-contact-mcp
    port: 9090
    transport: http
    description: MCP adapter for Suger API — Contact. One tool per consumed operation, routed inline through this capability's
      consumes block.
    tools:
    - name: list-contacts-organization
      description: List Contacts By Organization
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: suger-contact.listcontactsbyorganization
      with:
        orgId: tools.orgId
        limit: tools.limit
        offset: tools.offset
      outputParameters:
      - type: object
        mapping: $.
    - name: create-contact
      description: Create Contact
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: suger-contact.createcontact
      with:
        orgId: tools.orgId
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: batch-create-contacts
      description: Batch Create Contacts
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: suger-contact.batchcreatecontacts
      with:
        orgId: tools.orgId
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: get-contact
      description: Get Contact
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: suger-contact.getcontact
      with:
        orgId: tools.orgId
        contactId: tools.contactId
      outputParameters:
      - type: object
        mapping: $.
    - name: update-contact
      description: Update Contact
      hints:
        readOnly: false
        destructive: false
        idempotent: true
      call: suger-contact.updatecontact
      with:
        orgId: tools.orgId
        contactId: tools.contactId
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: remove-contact-buyer
      description: Remove Contact From Buyer
      hints:
        readOnly: false
        destructive: true
        idempotent: true
      call: suger-contact.removecontactfrombuyer
      with:
        orgId: tools.orgId
        buyerId: tools.buyerId
        contactId: tools.contactId
      outputParameters:
      - type: object
        mapping: $.
    - name: add-contact-buyer
      description: Add Contact To Buyer
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: suger-contact.addcontacttobuyer
      with:
        orgId: tools.orgId
        buyerId: tools.buyerId
        contactId: tools.contactId
      outputParameters:
      - type: object
        mapping: $.
    - name: remove-contact-offer
      description: Remove Contact From Offer
      hints:
        readOnly: false
        destructive: true
        idempotent: true
      call: suger-contact.removecontactfromoffer
      with:
        orgId: tools.orgId
        contactId: tools.contactId
        offerId: tools.offerId
      outputParameters:
      - type: object
        mapping: $.
    - name: add-contact-offer
      description: Add Contact To Offer
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: suger-contact.addcontacttooffer
      with:
        orgId: tools.orgId
        contactId: tools.contactId
        offerId: tools.offerId
      outputParameters:
      - type: object
        mapping: $.