Permit.io API — Relationship tuples

naftiko: 1.0.0-alpha2
info:
  label: Permit.io API — Relationship tuples
  description: 'Permit.io API — Relationship tuples. 6 operations. Lead operation: List Relationship Tuples. Self-contained
    Naftiko capability covering one Permit Io business surface.'
  tags:
  - Permit Io
  - Relationship tuples
  created: '2026-05-19'
  modified: '2026-05-19'
binds:
- namespace: env
  keys:
    PERMIT_IO_API_KEY: PERMIT_IO_API_KEY
capability:
  consumes:
  - type: http
    namespace: permit-io-relationship-tuples
    baseUri: ''
    description: Permit.io API — Relationship tuples business capability. Self-contained, no shared references.
    resources:
    - name: v2-facts-proj_id-env_id-relationship_tuples
      path: /v2/facts/{proj_id}/{env_id}/relationship_tuples
      operations:
      - name: listrelationshiptuples
        method: GET
        description: List Relationship Tuples
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: proj_id
          in: path
          type: string
          description: 'Either the unique id of the project, or the URL-friendly key of the project (i.e: the "slug").'
          required: true
        - name: env_id
          in: path
          type: string
          description: 'Either the unique id of the environment, or the URL-friendly key of the environment (i.e: the "slug").'
          required: true
        - name: detailed
          in: query
          type: boolean
          description: If true, will return the full subject and object resource instances.
        - name: include_total_count
          in: query
          type: boolean
          description: If true, returns the list of resource instances and the total count.
        - name: page
          in: query
          type: integer
          description: Page number of the results to fetch, starting at 1.
        - name: per_page
          in: query
          type: integer
          description: The number of results per page (max 100).
        - name: tenant
          in: query
          type: string
          description: The tenant key or id to filter by
        - name: subject
          in: query
          type: string
          description: The subject to filter by, accepts either the resource instance id or resource_type:resource_instance
        - name: relation
          in: query
          type: string
          description: The relation id or key to filter by
        - name: object
          in: query
          type: string
          description: The object to filter by, accepts either the resource instance id or resource_type:resource_instance
        - name: object_type
          in: query
          type: string
          description: The object type to filter by, accepts resource type id or key
        - name: subject_type
          in: query
          type: string
          description: The subject type to filter by, accepts resource type id or key
      - name: createrelationshiptuple
        method: POST
        description: Create Relationship Tuple
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: proj_id
          in: path
          type: string
          description: 'Either the unique id of the project, or the URL-friendly key of the project (i.e: the "slug").'
          required: true
        - name: env_id
          in: path
          type: string
          description: 'Either the unique id of the environment, or the URL-friendly key of the environment (i.e: the "slug").'
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
      - name: deleterelationshiptuple
        method: DELETE
        description: Delete Relationship Tuple
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: proj_id
          in: path
          type: string
          description: 'Either the unique id of the project, or the URL-friendly key of the project (i.e: the "slug").'
          required: true
        - name: env_id
          in: path
          type: string
          description: 'Either the unique id of the environment, or the URL-friendly key of the environment (i.e: the "slug").'
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: v2-facts-proj_id-env_id-relationship_tuples-bulk
      path: /v2/facts/{proj_id}/{env_id}/relationship_tuples/bulk
      operations:
      - name: bulkcreaterelationshiptuples
        method: POST
        description: Bulk create relationship tuples
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: proj_id
          in: path
          type: string
          description: 'Either the unique id of the project, or the URL-friendly key of the project (i.e: the "slug").'
          required: true
        - name: env_id
          in: path
          type: string
          description: 'Either the unique id of the environment, or the URL-friendly key of the environment (i.e: the "slug").'
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
      - name: bulkdeleterelationshiptuples
        method: DELETE
        description: Bulk Delete Relationship Tuples
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: proj_id
          in: path
          type: string
          description: 'Either the unique id of the project, or the URL-friendly key of the project (i.e: the "slug").'
          required: true
        - name: env_id
          in: path
          type: string
          description: 'Either the unique id of the environment, or the URL-friendly key of the environment (i.e: the "slug").'
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: v2-facts-proj_id-env_id-relationship_tuples-detailed
      path: /v2/facts/{proj_id}/{env_id}/relationship_tuples/detailed
      operations:
      - name: listrelationshiptuplesdetailed
        method: GET
        description: List Relationship Tuples Detailed
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: proj_id
          in: path
          type: string
          description: 'Either the unique id of the project, or the URL-friendly key of the project (i.e: the "slug").'
          required: true
        - name: env_id
          in: path
          type: string
          description: 'Either the unique id of the environment, or the URL-friendly key of the environment (i.e: the "slug").'
          required: true
        - name: page
          in: query
          type: integer
          description: Page number of the results to fetch, starting at 1.
        - name: per_page
          in: query
          type: integer
          description: The number of results per page (max 100).
        - name: tenant
          in: query
          type: string
          description: The tenant key or id to filter by
        - name: subject
          in: query
          type: string
          description: The subject to filter by, accepts either the resource instance id or resource_type:resource_instance
        - name: relation
          in: query
          type: string
          description: The relation id or key to filter by
        - name: object
          in: query
          type: string
          description: The object to filter by, accepts either the resource instance id or resource_type:resource_instance
        - name: object_type
          in: query
          type: string
          description: The object type to filter by, accepts resource type id or key
        - name: subject_type
          in: query
          type: string
          description: The subject type to filter by, accepts resource type id or key
    authentication:
      type: bearer
      token: '{{env.PERMIT_IO_API_KEY}}'
  exposes:
  - type: rest
    namespace: permit-io-relationship-tuples-rest
    port: 8080
    description: REST adapter for Permit.io API — Relationship tuples. One Spectral-compliant resource per consumed operation,
      prefixed with /v1.
    resources:
    - path: /v1/v2/facts/{proj-id}/{env-id}/relationship-tuples
      name: v2-facts-proj-id-env-id-relationship-tuples
      description: REST surface for v2-facts-proj_id-env_id-relationship_tuples.
      operations:
      - method: GET
        name: listrelationshiptuples
        description: List Relationship Tuples
        call: permit-io-relationship-tuples.listrelationshiptuples
        with:
          proj_id: rest.proj_id
          env_id: rest.env_id
          detailed: rest.detailed
          include_total_count: rest.include_total_count
          page: rest.page
          per_page: rest.per_page
          tenant: rest.tenant
          subject: rest.subject
          relation: rest.relation
          object: rest.object
          object_type: rest.object_type
          subject_type: rest.subject_type
        outputParameters:
        - type: object
          mapping: $.
      - method: POST
        name: createrelationshiptuple
        description: Create Relationship Tuple
        call: permit-io-relationship-tuples.createrelationshiptuple
        with:
          proj_id: rest.proj_id
          env_id: rest.env_id
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
      - method: DELETE
        name: deleterelationshiptuple
        description: Delete Relationship Tuple
        call: permit-io-relationship-tuples.deleterelationshiptuple
        with:
          proj_id: rest.proj_id
          env_id: rest.env_id
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v2/facts/{proj-id}/{env-id}/relationship-tuples/bulk
      name: v2-facts-proj-id-env-id-relationship-tuples-bulk
      description: REST surface for v2-facts-proj_id-env_id-relationship_tuples-bulk.
      operations:
      - method: POST
        name: bulkcreaterelationshiptuples
        description: Bulk create relationship tuples
        call: permit-io-relationship-tuples.bulkcreaterelationshiptuples
        with:
          proj_id: rest.proj_id
          env_id: rest.env_id
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
      - method: DELETE
        name: bulkdeleterelationshiptuples
        description: Bulk Delete Relationship Tuples
        call: permit-io-relationship-tuples.bulkdeleterelationshiptuples
        with:
          proj_id: rest.proj_id
          env_id: rest.env_id
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v2/facts/{proj-id}/{env-id}/relationship-tuples/detailed
      name: v2-facts-proj-id-env-id-relationship-tuples-detailed
      description: REST surface for v2-facts-proj_id-env_id-relationship_tuples-detailed.
      operations:
      - method: GET
        name: listrelationshiptuplesdetailed
        description: List Relationship Tuples Detailed
        call: permit-io-relationship-tuples.listrelationshiptuplesdetailed
        with:
          proj_id: rest.proj_id
          env_id: rest.env_id
          page: rest.page
          per_page: rest.per_page
          tenant: rest.tenant
          subject: rest.subject
          relation: rest.relation
          object: rest.object
          object_type: rest.object_type
          subject_type: rest.subject_type
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: permit-io-relationship-tuples-mcp
    port: 9090
    transport: http
    description: MCP adapter for Permit.io API — Relationship tuples. One tool per consumed operation, routed inline through
      this capability's consumes block.
    tools:
    - name: list-relationship-tuples
      description: List Relationship Tuples
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: permit-io-relationship-tuples.listrelationshiptuples
      with:
        proj_id: tools.proj_id
        env_id: tools.env_id
        detailed: tools.detailed
        include_total_count: tools.include_total_count
        page: tools.page
        per_page: tools.per_page
        tenant: tools.tenant
        subject: tools.subject
        relation: tools.relation
        object: tools.object
        object_type: tools.object_type
        subject_type: tools.subject_type
      outputParameters:
      - type: object
        mapping: $.
    - name: create-relationship-tuple
      description: Create Relationship Tuple
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: permit-io-relationship-tuples.createrelationshiptuple
      with:
        proj_id: tools.proj_id
        env_id: tools.env_id
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: delete-relationship-tuple
      description: Delete Relationship Tuple
      hints:
        readOnly: false
        destructive: true
        idempotent: true
      call: permit-io-relationship-tuples.deleterelationshiptuple
      with:
        proj_id: tools.proj_id
        env_id: tools.env_id
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: bulk-create-relationship-tuples
      description: Bulk create relationship tuples
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: permit-io-relationship-tuples.bulkcreaterelationshiptuples
      with:
        proj_id: tools.proj_id
        env_id: tools.env_id
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: bulk-delete-relationship-tuples
      description: Bulk Delete Relationship Tuples
      hints:
        readOnly: false
        destructive: true
        idempotent: true
      call: permit-io-relationship-tuples.bulkdeleterelationshiptuples
      with:
        proj_id: tools.proj_id
        env_id: tools.env_id
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: list-relationship-tuples-detailed
      description: List Relationship Tuples Detailed
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: permit-io-relationship-tuples.listrelationshiptuplesdetailed
      with:
        proj_id: tools.proj_id
        env_id: tools.env_id
        page: tools.page
        per_page: tools.per_page
        tenant: tools.tenant
        subject: tools.subject
        relation: tools.relation
        object: tools.object
        object_type: tools.object_type
        subject_type: tools.subject_type
      outputParameters:
      - type: object
        mapping: $.