Xero Projects API — Project

naftiko: 1.0.0-alpha2
info:
  label: Xero Projects API — Project
  description: 'Xero Projects API — Project. 16 operations. Lead operation: Xero Retrieves all projects. Self-contained Naftiko
    capability covering one Xero business surface.'
  tags:
  - Xero
  - Project
  created: '2026-05-19'
  modified: '2026-05-19'
binds:
- namespace: env
  keys:
    XERO_API_KEY: XERO_API_KEY
capability:
  consumes:
  - type: http
    namespace: projects-project
    baseUri: https://api.xero.com/projects.xro/2.0
    description: Xero Projects API — Project business capability. Self-contained, no shared references.
    resources:
    - name: Projects
      path: /Projects
      operations:
      - name: getprojects
        method: GET
        description: Xero Retrieves all projects
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: projectIds
          in: query
          type: array
          description: Search for all projects that match a comma separated list of projectIds
        - name: contactID
          in: query
          type: string
          description: Filter for projects for a specific contact
        - name: states
          in: query
          type: string
          description: Filter for projects in a particular state (INPROGRESS or CLOSED)
        - name: page
          in: query
          type: integer
          description: set to 1 by default. The requested number of the page in paged response - Must be a number greater
            than 0.
        - name: pageSize
          in: query
          type: integer
          description: Optional, it is set to 50 by default. The number of items to return per page in a paged response -
            Must be a number between 1 and 500.
      - name: createproject
        method: POST
        description: Xero Create one or more new projects
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: Projects-projectId
      path: /Projects/{projectId}
      operations:
      - name: getproject
        method: GET
        description: Xero Retrieves a single project
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: projectId
          in: path
          type: string
          description: You can specify an individual project by appending the projectId to the endpoint
          required: true
      - name: updateproject
        method: PUT
        description: Xero Updates a specific project
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: projectId
          in: path
          type: string
          description: You can specify an individual project by appending the projectId to the endpoint
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
      - name: patchproject
        method: PATCH
        description: Xero creates a project for the specified contact
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: projectId
          in: path
          type: string
          description: You can specify an individual project by appending the projectId to the endpoint
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: Projects-projectId-Tasks
      path: /Projects/{projectId}/Tasks
      operations:
      - name: gettasks
        method: GET
        description: Xero Retrieves all project tasks
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: projectId
          in: path
          type: string
          description: You can specify an individual project by appending the projectId to the endpoint
          required: true
        - name: page
          in: query
          type: integer
          description: Set to 1 by default. The requested number of the page in paged response - Must be a number greater
            than 0.
        - name: pageSize
          in: query
          type: integer
          description: Optional, it is set to 50 by default. The number of items to return per page in a paged response -
            Must be a number between 1 and 500.
        - name: taskIds
          in: query
          type: string
          description: Search for all tasks that match a comma separated list of taskIds, i.e. GET https://.../tasks?taskIds={taskID},{taskID}
      - name: createtask
        method: POST
        description: Xero Allows you to create a task
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: projectId
          in: path
          type: string
          description: You can create a task on a specified projectId
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: Projects-projectId-Tasks-taskId
      path: /Projects/{projectId}/Tasks/{taskId}
      operations:
      - name: gettask
        method: GET
        description: Xero Retrieves a single project task
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: projectId
          in: path
          type: string
          description: You can specify an individual project by appending the projectId to the endpoint
          required: true
        - name: taskId
          in: path
          type: string
          description: You can specify an individual task by appending the taskId to the endpoint, i.e. GET https://.../tasks/{taskID}
          required: true
      - name: updatetask
        method: PUT
        description: Xero Allows you to update a task
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: projectId
          in: path
          type: string
          description: You can specify an individual project by appending the projectId to the endpoint
          required: true
        - name: taskId
          in: path
          type: string
          description: You can specify an individual task by appending the id to the endpoint
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
      - name: deletetask
        method: DELETE
        description: Xero Allows you to delete a task
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: projectId
          in: path
          type: string
          description: You can specify an individual project by appending the projectId to the endpoint
          required: true
        - name: taskId
          in: path
          type: string
          description: You can specify an individual task by appending the id to the endpoint
          required: true
    - name: Projects-projectId-Time
      path: /Projects/{projectId}/Time
      operations:
      - name: gettimeentries
        method: GET
        description: Xero Retrieves all time entries associated with a specific project
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: projectId
          in: path
          type: string
          description: Identifier of the project, that the task (which the time entry is logged against) belongs to.
          required: true
        - name: userId
          in: query
          type: string
          description: The xero user identifier of the person who logged time.
        - name: taskId
          in: query
          type: string
          description: Identifier of the task that time entry is logged against.
        - name: invoiceId
          in: query
          type: string
          description: Finds all time entries for this invoice.
        - name: contactId
          in: query
          type: string
          description: Finds all time entries for this contact identifier.
        - name: page
          in: query
          type: integer
          description: Set to 1 by default. The requested number of the page in paged response - Must be a number greater
            than 0.
        - name: pageSize
          in: query
          type: integer
          description: Optional, it is set to 50 by default. The number of items to return per page in a paged response -
            Must be a number between 1 and 500.
        - name: states
          in: query
          type: array
          description: Comma-separated list of states to find. Will find all time entries that are in the status of whatever
            is specified.
        - name: isChargeable
          in: query
          type: boolean
          description: Finds all time entries which relate to tasks with the charge type `TIME` or `FIXED`.
        - name: dateAfterUtc
          in: query
          type: string
          description: ISO 8601 UTC date. Finds all time entries on or after this date filtered on the `dateUtc` field.
        - name: dateBeforeUtc
          in: query
          type: string
          description: ISO 8601 UTC date. Finds all time entries on or before this date filtered on the `dateUtc` field.
      - name: createtimeentry
        method: POST
        description: Xero Creates a time entry for a specific project
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: projectId
          in: path
          type: string
          description: You can specify an individual project by appending the projectId to the endpoint
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: Projects-projectId-Time-timeEntryId
      path: /Projects/{projectId}/Time/{timeEntryId}
      operations:
      - name: gettimeentry
        method: GET
        description: Xero Retrieves a single time entry for a specific project
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: projectId
          in: path
          type: string
          description: You can specify an individual project by appending the projectId to the endpoint
          required: true
        - name: timeEntryId
          in: path
          type: string
          description: You can specify an individual time entry by appending the id to the endpoint
          required: true
      - name: updatetimeentry
        method: PUT
        description: Xero Updates a time entry for a specific project
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: projectId
          in: path
          type: string
          description: You can specify an individual project by appending the projectId to the endpoint
          required: true
        - name: timeEntryId
          in: path
          type: string
          description: You can specify an individual time entry by appending the id to the endpoint
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
      - name: deletetimeentry
        method: DELETE
        description: Xero Deletes a time entry for a specific project
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: projectId
          in: path
          type: string
          description: You can specify an individual project by appending the projectId to the endpoint
          required: true
        - name: timeEntryId
          in: path
          type: string
          description: You can specify an individual task by appending the id to the endpoint
          required: true
    - name: ProjectsUsers
      path: /ProjectsUsers
      operations:
      - name: getprojectusers
        method: GET
        description: Xero Retrieves a list of all project users
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: page
          in: query
          type: integer
          description: set to 1 by default. The requested number of the page in paged response - Must be a number greater
            than 0.
        - name: pageSize
          in: query
          type: integer
          description: Optional, it is set to 50 by default. The number of items to return per page in a paged response -
            Must be a number between 1 and 500.
    authentication:
      type: bearer
      token: '{{env.XERO_API_KEY}}'
  exposes:
  - type: rest
    namespace: projects-project-rest
    port: 8080
    description: REST adapter for Xero Projects API — Project. One Spectral-compliant resource per consumed operation, prefixed
      with /v1.
    resources:
    - path: /v1/projects
      name: projects
      description: REST surface for Projects.
      operations:
      - method: GET
        name: getprojects
        description: Xero Retrieves all projects
        call: projects-project.getprojects
        with:
          projectIds: rest.projectIds
          contactID: rest.contactID
          states: rest.states
          page: rest.page
          pageSize: rest.pageSize
        outputParameters:
        - type: object
          mapping: $.
      - method: POST
        name: createproject
        description: Xero Create one or more new projects
        call: projects-project.createproject
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/projects/{projectid}
      name: projects-projectid
      description: REST surface for Projects-projectId.
      operations:
      - method: GET
        name: getproject
        description: Xero Retrieves a single project
        call: projects-project.getproject
        with:
          projectId: rest.projectId
        outputParameters:
        - type: object
          mapping: $.
      - method: PUT
        name: updateproject
        description: Xero Updates a specific project
        call: projects-project.updateproject
        with:
          projectId: rest.projectId
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
      - method: PATCH
        name: patchproject
        description: Xero creates a project for the specified contact
        call: projects-project.patchproject
        with:
          projectId: rest.projectId
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/projects/{projectid}/tasks
      name: projects-projectid-tasks
      description: REST surface for Projects-projectId-Tasks.
      operations:
      - method: GET
        name: gettasks
        description: Xero Retrieves all project tasks
        call: projects-project.gettasks
        with:
          projectId: rest.projectId
          page: rest.page
          pageSize: rest.pageSize
          taskIds: rest.taskIds
        outputParameters:
        - type: object
          mapping: $.
      - method: POST
        name: createtask
        description: Xero Allows you to create a task
        call: projects-project.createtask
        with:
          projectId: rest.projectId
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/projects/{projectid}/tasks/{taskid}
      name: projects-projectid-tasks-taskid
      description: REST surface for Projects-projectId-Tasks-taskId.
      operations:
      - method: GET
        name: gettask
        description: Xero Retrieves a single project task
        call: projects-project.gettask
        with:
          projectId: rest.projectId
          taskId: rest.taskId
        outputParameters:
        - type: object
          mapping: $.
      - method: PUT
        name: updatetask
        description: Xero Allows you to update a task
        call: projects-project.updatetask
        with:
          projectId: rest.projectId
          taskId: rest.taskId
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
      - method: DELETE
        name: deletetask
        description: Xero Allows you to delete a task
        call: projects-project.deletetask
        with:
          projectId: rest.projectId
          taskId: rest.taskId
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/projects/{projectid}/time
      name: projects-projectid-time
      description: REST surface for Projects-projectId-Time.
      operations:
      - method: GET
        name: gettimeentries
        description: Xero Retrieves all time entries associated with a specific project
        call: projects-project.gettimeentries
        with:
          projectId: rest.projectId
          userId: rest.userId
          taskId: rest.taskId
          invoiceId: rest.invoiceId
          contactId: rest.contactId
          page: rest.page
          pageSize: rest.pageSize
          states: rest.states
          isChargeable: rest.isChargeable
          dateAfterUtc: rest.dateAfterUtc
          dateBeforeUtc: rest.dateBeforeUtc
        outputParameters:
        - type: object
          mapping: $.
      - method: POST
        name: createtimeentry
        description: Xero Creates a time entry for a specific project
        call: projects-project.createtimeentry
        with:
          projectId: rest.projectId
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/projects/{projectid}/time/{timeentryid}
      name: projects-projectid-time-timeentryid
      description: REST surface for Projects-projectId-Time-timeEntryId.
      operations:
      - method: GET
        name: gettimeentry
        description: Xero Retrieves a single time entry for a specific project
        call: projects-project.gettimeentry
        with:
          projectId: rest.projectId
          timeEntryId: rest.timeEntryId
        outputParameters:
        - type: object
          mapping: $.
      - method: PUT
        name: updatetimeentry
        description: Xero Updates a time entry for a specific project
        call: projects-project.updatetimeentry
        with:
          projectId: rest.projectId
          timeEntryId: rest.timeEntryId
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
      - method: DELETE
        name: deletetimeentry
        description: Xero Deletes a time entry for a specific project
        call: projects-project.deletetimeentry
        with:
          projectId: rest.projectId
          timeEntryId: rest.timeEntryId
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/projectsusers
      name: projectsusers
      description: REST surface for ProjectsUsers.
      operations:
      - method: GET
        name: getprojectusers
        description: Xero Retrieves a list of all project users
        call: projects-project.getprojectusers
        with:
          page: rest.page
          pageSize: rest.pageSize
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: projects-project-mcp
    port: 9090
    transport: http
    description: MCP adapter for Xero Projects API — Project. One tool per consumed operation, routed inline through this
      capability's consumes block.
    tools:
    - name: xero-retrieves-all-projects
      description: Xero Retrieves all projects
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: projects-project.getprojects
      with:
        projectIds: tools.projectIds
        contactID: tools.contactID
        states: tools.states
        page: tools.page
        pageSize: tools.pageSize
      outputParameters:
      - type: object
        mapping: $.
    - name: xero-create-one-more-new
      description: Xero Create one or more new projects
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: projects-project.createproject
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: xero-retrieves-single-project
      description: Xero Retrieves a single project
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: projects-project.getproject
      with:
        projectId: tools.projectId
      outputParameters:
      - type: object
        mapping: $.
    - name: xero-updates-specific-project
      description: Xero Updates a specific project
      hints:
        readOnly: false
        destructive: false
        idempotent: true
      call: projects-project.updateproject
      with:
        projectId: tools.projectId
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: xero-creates-project-specified-contact
      description: Xero creates a project for the specified contact
      hints:
        readOnly: false
        destructive: false
        idempotent: true
      call: projects-project.patchproject
      with:
        projectId: tools.projectId
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: xero-retrieves-all-project-tasks
      description: Xero Retrieves all project tasks
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: projects-project.gettasks
      with:
        projectId: tools.projectId
        page: tools.page
        pageSize: tools.pageSize
        taskIds: tools.taskIds
      outputParameters:
      - type: object
        mapping: $.
    - name: xero-allows-you-create-task
      description: Xero Allows you to create a task
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: projects-project.createtask
      with:
        projectId: tools.projectId
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: xero-retrieves-single-project-task
      description: Xero Retrieves a single project task
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: projects-project.gettask
      with:
        projectId: tools.projectId
        taskId: tools.taskId
      outputParameters:
      - type: object
        mapping: $.
    - name: xero-allows-you-update-task
      description: Xero Allows you to update a task
      hints:
        readOnly: false
        destructive: false
        idempotent: true
      call: projects-project.updatetask
      with:
        projectId: tools.projectId
        taskId: tools.taskId
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: xero-allows-you-delete-task
      description: Xero Allows you to delete a task
      hints:
        readOnly: false
        destructive: true
        idempotent: true
      call: projects-project.deletetask
      with:
        projectId: tools.projectId
        taskId: tools.taskId
      outputParameters:
      - type: object
        mapping: $.
    - name: xero-retrieves-all-time-entries
      description: Xero Retrieves all time entries associated with a specific project
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: projects-project.gettimeentries
      with:
        projectId: tools.projectId
        userId: tools.userId
        taskId: tools.taskId
        invoiceId: tools.invoiceId
        contactId: tools.contactId
        page: tools.page
        pageSize: tools.pageSize
        states: tools.states
        isChargeable: tools.isChargeable
        dateAfterUtc: tools.dateAfterUtc
        dateBeforeUtc: tools.dateBeforeUtc
      outputParameters:
      - type: object
        mapping: $.
    - name: xero-creates-time-entry-specific
      description: Xero Creates a time entry for a specific project
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: projects-project.createtimeentry
      with:
        projectId: tools.projectId
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: xero-retrieves-single-time-entry
      description: Xero Retrieves a single time entry for a specific project
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: projects-project.gettimeentry
      with:
        projectId: tools.projectId
        timeEntryId: tools.timeEntryId
      outputParameters:
      - type: object
        mapping: $.
    - name: xero-updates-time-entry-specific
      description: Xero Updates a time entry for a specific project
      hints:
        readOnly: false
        destructive: false
        idempotent: true
      call: projects-project.updatetimeentry
      with:
        projectId: tools.projectId
        timeEntryId: tools.timeEntryId
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: xero-deletes-time-entry-specific
      description: Xero Deletes a time entry for a specific project
      hints:
        readOnly: false
        destructive: true
        idempotent: true
      call: projects-project.deletetimeentry
      with:
        projectId: tools.projectId
        timeEntryId: tools.timeEntryId
      outputParameters:
      - type: object
        mapping: $.
    - name: xero-retrieves-list-all-project
      description: Xero Retrieves a list of all project users
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: projects-project.getprojectusers
      with:
        page: tools.page
        pageSize: tools.pageSize
      outputParameters:
      - type: object
        mapping: $.