Conduit API: Using Edit Endpoints

Phorge Administrator and User Documentation (API Documentation)

Describes how to use edit endpoints to create and update objects.

Overview

Many applications provide edit endpoints, which are the primary way to create and update objects (like tasks) using the API.

To create or edit an object, you'll build a list of transactions and pass them to the endpoint. Each transaction applies a change to a field or property on the object.

For example, a transaction might change the title of an object or add subscribers.

When creating an object, transactions will be applied to an empty object. When editing an object, transactions will be applied to an existing object.

The best reference for a particular edit endpoint is the Conduit API console. For example, you can find the console page for maniphest.edit by navigating to Conduit → maniphest.edit in the web UI. This page contains detailed information about the endpoint and how it can be used.

Creating Objects

To create objects, pass a list of transactions but leave objectIdentfier blank. This tells the endpoint that you want to create a new, empty object and then apply the transactions to it.

Editing Objects

To edit objects, pass a list of transactions and use objectIdentifier to specify which object to apply them to. You can normally pass an ID or PHID, and many applications also allow you to pass a monogram (for example, you can edit a task by passing T123).

Building Transactions

When creating or editing objects, you'll build a list of transactions to apply. This transaction list will look something like this:

[
  {
    "type": "title",
    "value": "Assemble in the barnyard"
  },
  {
    "type": "description",
    "value": "All animals should assemble in the barnyard promptly."
  },
  {
    "type": "subscribers.add",
    "value": ["dog", "cat", "mouse"]
  }
]

Applied to an empty object (say, a task), these transactions would create a new task with the specified title, description and subscribers.

Applied to an existing object, they would retitle the task, change its description, and add new subscribers.

The particular transactions available on each object are documented on the Conduit API console page for that object.

Return Type

Return values look something like this for now:

{
  "object": {
    "phid": "PHID-XXXX-1111"
  },
  "transactions": [
    {
      "phid": "PHID-YYYY-1111",
    },
    {
      "phid": "PHID-YYYY-2222",
    }
  ]
}

The object key contains information about the object which was created or edited.

The transactions key contains information about the transactions which were actually applied. For many reasons, the transactions which actually apply may be greater or fewer in number than the transactions you provided, or may differ in their nature in other ways.

Next Steps

Continue by:

• returning to the Conduit API Overview.