Channel Lifecycle

Endpoints:

Note that channels will appear "unread" if there is no stream marker for the user+channel, or if the marker's id is lower than the most recent message in the channel.

For details on how to use channels for private messaging, look at How To Private Message.

POST /channels

Token: user

Scope: messages

Create a channel.

POST Body Data

Name Description
type Required String composed of letters, numbers, underscore, period, and dash. Up to 128 characters
acl Valid ACL object. By default, everything but type and user is editable after creating the channel! Be sure to restrict editing if you want to prevent it, and read How to ACL
raw Embedded raw values.
Example
curl "https://api.pnut.io/v1/channels" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H "Content-Type: application/json" \
    -d "{
  \"type\":\"com.example.site\",
  \"acl\":{
    \"full\": {
      \"user_ids\": [
        4,\"@wife\"
      ],
      \"immutable\":false
    },
    \"read\": {
      \"any_user\":true
    }
  }
}" \
    -X POST \
    -H "X-Pretty-Json: 1"

Returns the created channel

{
    "meta": {
        "code": 201
    },
    "data": {"...Channel Object..."}
}

PUT /channels/{channel_id}

Token: user

Scope: messages

Update a channel. PUT and PATCH may be used.

POST Body Data

Name Description
acl Valid ACL object. Only mutable ACLs can be updated. Full-access users and the channel creator can edit a channel, but only the creator can change who is a full-access user. Be sure to restrict editing if you want to prevent it, and read How to ACL
raw Embedded raw values. Not deleted unless explicitly set to empty values for each type.
Example
curl "https://api.pnut.io/v1/channels/13" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H "Content-Type: application/json" \
    -d "{
  \"acl\":{
    \"full\": {
      \"user_ids\": [
        4
      ]
    }
  }
}" \
    -X PUT \
    -H "X-Pretty-Json: 1"

Returns the updated channel

{
    "meta": {
        "code": 200
    },
    "data": {"...Channel Object..."}
}

PUT /channels/{channel_id}/owner

Token: user

Scope: messages

Change the owner of a channel.

Can not be done to io.pnut.core.pm-type channels.

Can only be done by the current owner of the channel. The current owner will automatically be made a full access user of the channel.

POST Body Data

Name Description
owner_id User ID or @-username of new owner.
Example
curl "https://api.pnut.io/v1/channels/13/owner" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H "Content-Type: application/json" \
    -d "{
  \"owner_id\": \"2\"
}" \
    -X PUT \
    -H "X-Pretty-Json: 1"

Returns the updated channel

{
    "meta": {
        "code": 200
    },
    "data": {"...Channel Object..."}
}

DELETE /channels/{channel_id}

Token: user

Scope: messages

Deactivate a channel. Only the creator of a channel can deactivate it. Deactivating a channel removes all subscriptions to the channel, but does nothing to the contents. It is irreversible. io.pnut.core.pm-type channels cannot be deactivated.

Example
curl "https://api.pnut.io/v1/channels/13" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -X DELETE \
    -H "X-Pretty-Json: 1"

Returns the deactivated channel

{
    "meta": {
        "code": 200
    },
    "data": {"....Channel Object..."}
}