NAV
http curl javascript

Introduction

var PagedipData = require("@beneaththeink/pagedip-data");
var client = new PagedipData({
  apiUrl: "https://api.pagedip.com"
});

This is the Pagedip REST API documentation. This still a work in progress and is missing some information.

If you have issues with the API please contact us directly at info@beneaththeink.com.

Authentication

GET / HTTP/1.1
Host: api.pagedip.com
Authorization: Bearer API_TOKEN
curl https://api.pagedip.com \
  -H "Authorization: Bearer API_TOKEN"
client.authorize(API_TOKEN);

The Pagedip API uses UUID-based tokens to authenticate requests without needing to provide a username and password for every request. This method of authorization works with both the API as well as directly with CouchDB.

To authorize a request, add an Authorization header with the keyword Bearer and a valid API token.

Authorization: Bearer API_TOKEN

Obtaining an API Token

POST /tokens HTTP/1.1
Content-Type: application/json
Host: api.pagedip.com
Content-Length: 77

{
  "username": "USERNAME",
  "password": "PASSWORD",
  "label": "MyToken"
}
curl -X POST https://api.pagedip.com/tokens \
  -d "username=USERNAME" \
  -d "password=PASSWORD" \
  -d "label=MyToken"
client.signin(USERNAME, PASSWORD).then(function() {
  // client is now authorized
}).catch(function(e) {
  console.error(e);
});

Exchange a username and password for an API token by POSTing to the /tokens endpoint. This will create a new API token.

HTTP Request

POST https://api.pagedip.com/tokens

Request Fields

Fields Type Description
username String A Pagedip user's name.
password String The password of the user.
label String A label for the token. Useful for the user to identify this token later.

Response Fields

{
  "ok": true,
  "id": "23f69510-76f0-11e6-abef-1fb827d86309",
  "token": "API_TOKEN",
  "created": "2016-09-10T00:47:24.898Z",
  "label": "MyToken"
}
Field Type Description
id String The token's ID. This is used to uniquely identify the token later.
token String The API token to authenticate with. This is the only time the token is displayed so be sure to save it somewhere.
created String The time and date this API token was created as an ISO 8601 date string.
label String The label set on the token.

Errors

Code Status Description
EBADAUTH 401 The username or password provided was incorrect.

Getting Info about an API Token

GET /tokens/23f69510-76f0-11e6-abef-1fb827d86309 HTTP/1.1
Host: api.pagedip.com
Authorization: Bearer API_TOKEN
curl https://api.pagedip.com/tokens/23f69510-76f0-11e6-abef-1fb827d86309 \
  -H "Authorization: Bearer API_TOKEN"
client.auth.info().then(function(data) {
  console.log(data);
}).catch(function(e) {
  console.error(e);
});

To retrieve details about an API token, send a GET request to the /tokens endpoint with the id of the token you desire info on.

HTTP Request

GET https://api.pagedip.com/tokens/:id

Response Fields

{
  "ok": true,
  "id": "23f69510-76f0-11e6-abef-1fb827d86309",
  "created": "2016-09-10T00:47:24.898Z",
  "label": "MyToken"
}
Field Type Description
id String The token's ID. This is used to uniquely identify the token later.
created String The time and date this API token was created as an ISO 8601 date string.
label String The label set on the token.

Errors

Code Status Description
EBADTOKEN 401 The API token was missing or invalid.
ENOTOKEN 404 The requested API token does not exist.

Destroying an API Token

DELETE /tokens/23f69510-76f0-11e6-abef-1fb827d86309 HTTP/1.1
Host: api.pagedip.com
Authorization: Bearer API_TOKEN
curl -X DELETE https://api.pagedip.com/tokens/23f69510-76f0-11e6-abef-1fb827d86309 \
  -H "Authorization: Bearer API_TOKEN"
client.signout().then(function() {
  // client is no longer authorized
}).catch(function(e) {
  console.error(e);
});

Destroying an API token is similar to signing a user out. This will prevent all future API requests made with this token.

HTTP Request

DELETE https://api.pagedip.com/tokens/:id

Response Fields

{
  "ok": true,
  "id": "23f69510-76f0-11e6-abef-1fb827d86309",
  "created": "2016-09-10T00:47:24.898Z",
  "label": "MyToken",
  "_deleted": true
}
Field Type Description
id String The token's ID. This is used to uniquely identify the token later.
created String The time and date this API token was created as an ISO 8601 date string.
label String The label set on the token.
_deleted Boolean Set to true to show this api token has been destroyed.

Errors

Code Status Description
EBADTOKEN 401 The API token was missing or invalid.
ENOTOKEN 404 The requested API token does not exist.

Accounts

Pagedip accounts are used for accessing data within the API. There are two types of Pagedip accounts:

Account names become a Pagedip URL in the form of [name].pagedip.com. These domains provide direct access to Pagedips created under the account.

Create an Account

User request:

POST /account HTTP/1.1
Host: api.pagedip.com
Content-Type: application/json
Content-Length: 95

{
  "name": "tyler",
  "password": "test",
  "email": "tyler@tylerjohnson.me",
  "tos": "yes"
}
curl -X POST https://api.pagedip.com/account \
  -d "name=tyler" \
  -d "password=test" \
  -d "email=tyler@tylerjohnson.me" \
  -d "tos=yes"
client.account("tyler").create({
  password: "test",
  email: "tyler@tylerjohnson.me",
  tos: "yes"
}).then(function(data) {
  console.log(data);
}).catch(function(e) {
  console.error(e);
});

Organization request:

POST /account HTTP/1.1
Host: api.pagedip.com
Authorization: Bearer API_TOKEN
Content-Type: application/json
Content-Length: 101

{
  "name": "bigbusinessinc",
  "email": "big@business.com",
  "organization": true,
  "tos": "yes"
}
curl -X POST https://api.pagedip.com/account \
  -H "Authorization: Bearer API_TOKEN" \
  -d "name=bigbusinessinc" \
  -d "email=big@business.com" \
  -d "organization=true" \
  -d "tos=yes"
client.account("bigbusinessinc").create({
  email: "big@business.com",
  organization: true,
  tos: "yes"
}).then(function(data) {
  console.log(data);
}).catch(function(e) {
  console.error(e);
});

Create a new Pagedip account by POSTing to the /account endpoint.

HTTP Request

POST https://api.pagedip.com/account

Request Fields

General

Field Type Description
name String The account's unique username. This is used to sign in, and will become the account's personal Pagedip URL https://[name].pagedip.com.
fullname String The full name of the account, usually the person's or organization's real name.
email String A valid email address for the new account. Users are sent welcome emails, organizations are not.
tos String Indicates that whomever is creating the account has agreed to the Pagedip Terms of Service. This must be set to "yes".

User

Field Type Description
password String A secret password to protect the user account.

Organization

Field Type Description
organization Boolean Set to true to create an organization account and not a user account.

Response Fields

User response:

{
  "ok": true,
  "name": "tyler",
  "email": "tyler@tylerjohnson.me",
  "roles": [],
  "created": "2016-03-19T01:51:14.502Z",
  "last_updated": "2016-03-19T01:51:14.502Z",
  "_links": {
    "account": "/account/tyler",
    "password": "/account/tyler/password",
    "organizations": "/account/tyler/organizations"
  }
}

Organization response:

{
  "ok": true,
  "name": "bigbusinessinc",
  "email": "big@business.com",
  "organization": true,
  "roles": [],
  "created": "2016-03-19T02:19:21.227Z",
  "last_updated": "2016-03-19T02:19:21.227Z",
  "owners": [
    "tyler"
  ],
  "_links": {
    "account": "/account/bigbusinessinc"
  }
}
Field Type Description
name String The account username.
email String The account email address.
fullname String The full name of the account, usually the person's or organization's real name.
roles String[] An array of user permissions, including organization access.
created Date Exact moment of the Pagedip's creation, in the form of an ISO 8601 date string.
last_updated Date The last time the metadata document was updated, as an ISO 8601 date string.
organization Boolean Set to true when the account is an organization.
owners String[] An array of organization owner usernames.
_links Object A mapping of relevant api URLs pertaining to this account.

Errors

Code Status Description
ETOS 400 This error code signals an invalid value for the tos field.
ENONAME 400 The request is missing a name field.
EBADPASS 400 The request is missing a password field.
EBADINPUT 400 This means there was something wrong with the incoming request data.
EACCESS 403 This means the authenticated user lacks permission for the requested resource.
EEXISTS 409 Returned when a user account already exists with the given username.

Get Account Details

GET /account/tyler HTTP/1.1
Host: api.pagedip.com
Authorization: Bearer API_TOKEN
curl https://api.pagedip.com/account/tyler \
  -H "Authorization: Bearer API_TOKEN"
client.account("tyler").fetch().then(function(data) {
  console.log(data);
}).catch(function(e) {
  console.error(e);
});

Fetch account information by sending a GET request to the /account endpoint.

You do not need to be authenticated to fetch a Pagedip account, however, you will only be able to see the account's public profile. You will need to be authenticated to see extended account information.

HTTP Request

GET https://api.pagedip.com/account
GET https://api.pagedip.com/account/:name

Parameter Description
name The account's username to fetch details for. If not provided, the endpoint will respond with the authenticated user's profile.

Response Fields

User response:

{
  "ok": true,
  "name": "tyler",
  "email": "tyler@tylerjohnson.me",
  "roles": [],
  "created": "2016-03-19T01:51:14.502Z",
  "last_updated": "2016-03-19T01:51:14.502Z",
  "_links": {
    "account": "/account/tyler",
    "password": "/account/tyler/password",
    "organizations": "/account/tyler/organizations"
  }
}

Organization response:

{
  "ok": true,
  "name": "bigbusinessinc",
  "email": "big@business.com",
  "organization": true,
  "roles": [],
  "created": "2016-03-19T02:19:21.227Z",
  "last_updated": "2016-03-19T02:19:21.227Z",
  "owners": [
    "tyler"
  ],
  "_links": {
    "account": "/account/bigbusinessinc"
  }
}
Field Type Description
name String The account username.
email String The account email address.
fullname String The full name of the account, usually the person's or organization's real name.
roles String[] An array of user permissions, including organization access.
created Date Exact moment of the Pagedip's creation, in the form of an ISO 8601 date string.
last_updated Date The last time the metadata document was updated, as an ISO 8601 date string.
organization Boolean Set to true when the account is an organization.
owners String[] An array of organization owner usernames.
_links Object A mapping of relevant api URLs pertaining to this account.

Errors

Code Status Description
ENOUSER 404 Requested user does not exist.

Update Account Details

PUT /account/tyler HTTP/1.1
Host: api.pagedip.com
Authorization: Bearer API_TOKEN
Content-Type: application/json
Content-Length: 71

{
  "email": "tyler@beneaththeink.com",
  "fullname": "Tyler Johnson"
}
curl -X PUT https://api.pagedip.com/account/tyler \
    -H "Authorization: Bearer API_TOKEN" \
    -d "email=tyler@beneaththeink.com" \
    -d "fullname=Tyler Johnson"
client.account("tyler").update({
  email: "tyler@beneaththeink.com",
  fullname: "Tyler Johnson"
}).then(function(data) {
  console.log(data);
}).catch(function(e) {
  console.error(e);
});

Modify account information by sending a PUT request to the /account endpoint.

This performs a hard reset on the account, meaning that if the request is missing a field, it will be removed from the account. This, of course, does not apply to immutable fields, like name and roles.

HTTP Request

PUT https://api.pagedip.com/account
PUT https://api.pagedip.com/account/:name

Parameter Description
name The account's username to update details for. If not provided, the endpoint will update the authenticated user's account.

Request Fields

Field Type Description
name String The username of the account to update. This is only used if the name is not provided in the URL.
fullname String The full name of the account, usually the person's or organization's real name.
email String A valid email address for the new account. Users are sent welcome emails, organizations are not.

Response Fields

User response:

{
  "ok": true,
  "email": "tyler@beneaththeink.com",
  "fullname": "Tyler Johnson",
  "name": "tyler",
  "roles": [],
  "created": "2016-03-19T02:19:21.227Z",
  "last_updated": "2016-03-21T20:18:20.306Z",
  "_links": {
    "account": "/account/tyler",
    "password": "/account/tyler/password",
    "organizations": "/account/tyler/organizations"
  }
}

Organization response:

{
  "ok": true,
  "name": "bigbusinessinc",
  "email": "big@business.com",
  "organization": true,
  "roles": [],
  "created": "2016-03-19T02:19:21.227Z",
  "last_updated": "2016-03-19T02:19:21.227Z",
  "owners": [
    "tyler"
  ],
  "_links": {
    "account": "/account/bigbusinessinc"
  }
}
Field Type Description
name String The account username.
email String The account email address.
fullname String The full name of the account, usually the person's or organization's real name.
roles String[] An array of user permissions, including organization access.
created Date Exact moment of the Pagedip's creation, in the form of an ISO 8601 date string.
last_updated Date The last time the metadata document was updated, as an ISO 8601 date string.
organization Boolean Set to true when the account is an organization.
owners String[] An array of organization owner usernames.
_links Object A mapping of relevant api URLs pertaining to this account.

Errors

Code Status Description
EBADINPUT 400 This means there was something wrong with the incoming request data.
EACCESS 403 This means the authenticated user lacks permission for the requested resource.
ENOUSER 404 Requested user does not exist.

Change User Password

POST /account/tyler/password HTTP/1.1
Host: api.pagedip.com
Authorization: Bearer API_TOKEN
Content-Type: application/json
Content-Length: 34

{
  "password": "super$ecret!!1"
}
curl -X POST https://api.pagedip.com/account/tyler/password \
    -H "Authorization: Bearer API_TOKEN" \
    -d 'password=super$ecret!!1'
client.account().changePassword("super$ecret!!1").catch(function(e) {
  console.error(e);
});

To change your account password, send a new password to the /account/:name/password endpoint. Only the authenticated user's password can be changed.

HTTP Request

POST https://api.pagedip.com/account/:name/password

Parameter Description
name The account's username to change the password.

Request Fields

Field Type Description
password String The new password the account should be protected with.

Response Fields

{
  "ok": true
}

There are no response fields for this request.

Errors

Code Status Description
EBADINPUT 400 This means there was something wrong with the incoming request data.
EACCESS 403 This means the authenticated user lacks permission for the requested resource.

Organizations

Organizations provide a shared Pagedip namespace for many users. Since organizations are just accounts, they can be created and edited via the /account endpoint.

There are two levels of membership for users in an organization:

List Organizations

GET /account/tyler/organizations HTTP/1.1
Host: api.pagedip.com
Authorization: Bearer API_TOKEN
curl https://api.pagedip.com/account/tyler/organizations \
    -H "Authorization: Bearer API_TOKEN"
client.account().organizations().then(function(orgs) {
  console.log(orgs);
}).catch(function(e) {
  console.error(e);
});

List all organizations a user is a member of using the /account/:name/organizations endpoint.

HTTP Request

GET https://api.pagedip.com/account/:name/organizations

Parameter Description
name The account's username to get organizations for. Must match the username in the API token.

Response Fields

{
  "ok": true,
  "total_rows": 1,
  "rows": [
    {
      "name": "bigbusinessinc",
      "email": "big@business.com",
      "organization": true,
      "roles": [],
      "created": "2016-03-19T02:19:21.227Z",
      "last_updated": "2016-03-19T02:19:21.227Z",
      "owners": [
        "tyler"
      ],
      "_links": {
        "account": "/account/bigbusinessinc"
      }
    }
  ]
}

The response will be a list of organization objects with the following fields:

Field Type Description
name String The account username.
email String The account email address.
fullname String The full name of the account, usually the person's or organization's real name.
roles String[] An array of user permissions, including organization access.
created Date Exact moment of the Pagedip's creation, in the form of an ISO 8601 date string.
last_updated Date The last time the metadata document was updated, as an ISO 8601 date string.
organization Boolean Set to true when the account is an organization.
owners String[] An array of organization owner usernames.
_links Object A mapping of relevant api URLs pertaining to this account.

Errors

Code Status Description
EACCESS 403 This means the authenticated user lacks permission for the requested resource.

List Members

GET /account/bigbusinessinc/members HTTP/1.1
Host: api.pagedip.com
Authorization: Bearer API_TOKEN
curl https://api.pagedip.com/account/bigbusinessinc/members \
    -H "Authorization: Bearer API_TOKEN"
client.account("bigbusinessinc").members.list()
  .then(function(members) {
    console.log(members);
  }).catch(function(e) {
    console.error(e);
  });

List the members of an organization with the /account/:name/members endpoint.

HTTP Request

GET https://api.pagedip.com/account/:name/members

Parameter Description
name The organizations's name to get members for.

Response Fields

{
  "ok": true,
  "total_rows": 1,
  "rows": [
    {
      "owner": true,
      "name": "tyler",
      "_links": {
        "account": "/account/tyler"
      }
    }
  ]
}

The response will be a list of account objects with the following fields:

Field Type Description
name String The member's username.
owner Boolean Set to true when this member is an organization owner.
_links Object A mapping of relevant api URLs pertaining to this account.

Errors

Code Status Description
ENOTORG 400 The requested account is not an organization.
EACCESS 403 This means the authenticated user lacks permission for the requested resource.
ENOUSER 404 The requested account does not exist.

Add Members and Modify Ownership

PUT /account/bigbusinessinc/members HTTP/1.1
Host: api.pagedip.com
Authorization: Bearer API_TOKEN
Content-Type: application/json
Content-Length: 39

{
  "name": "alice",
  "owner": false
}
curl -X PUT http://api.pagedip.com/account/bigbusinessinc/members \
    -H "Authorization: Bearer API_TOKEN" \
    -d "name=alice" \
    -d "owner="
client.account("bigbusinessinc").members.add("alice", false)
  .then(function(result) {
    console.log(result);
  }).catch(function(e) {
    console.error(e);
  });

Add a member to an organization by sending a PUT request the members endpoint. Existing users can be promoted and demoted as owners using this endpoint as well.

HTTP Request

PUT https://api.pagedip.com/account/:name/members

Parameter Description
name The organizations's name to add a member to.

Request Fields

Field Type Description
name String The name of the user to add as member.
owner Boolean When set to true, the member will be promoted to owner.

Response Fields

{
  "ok": true,
  "owner": false,
  "name": "alice",
  "_links": {
    "account": "/account/alice"
  }
}
Field Type Description
name String The member's username.
owner Boolean Set to true when this member is an organization owner.
_links Object A mapping of relevant api URLs pertaining to this account.

Errors

Code Status Description
ENOTORG 400 The requested account is not an organization.
EORG 400 Organizations cannot be added as a member to other organizations.
EBADINPUT 400 This means there was something wrong with the incoming request data.
ENOOWNER 400 Organizations must have at least one owner.
EACCESS 403 This means the authenticated user lacks permission for the requested resource.
ENOUSER 404 The requested account does not exist.

Remove Members

DELETE /account/bigbusinessinc/members HTTP/1.1
Host: api.pagedip.com
Authorization: Bearer API_TOKEN
Content-Type: application/json
Content-Length: 21

{
  "name": "alice"
}
curl -X DELETE https://api.pagedip.com/account/bigbusinessinc/members \
    -H "Authorization: Bearer API_TOKEN" \
    -d "name=alice"
client.account("bigbusinessinc").members.remove("alice")
  .then(function(result) {
    console.log(result);
  }).catch(function(e) {
    console.error(e);
  });

Remove members from an organization by sending a DELETE request to the members endpoint.

HTTP Request

DELETE https://api.pagedip.com/account/:name/members

Parameter Description
name The organizations's name to remove a member from.

Request Fields

Field Type Description
name String The name of the user to remove as member.

Response Fields

{
  "ok": true,
  "owner": false,
  "name": "alice",
  "_links": {
    "account": "/account/alice"
  }
}
Field Type Description
name String The member's username that was just removed.
owner Boolean Set to true when this member was an organization owner.
_links Object A mapping of relevant api URLs pertaining to this account.

Errors

Code Status Description
ENOTORG 400 The requested account is not an organization.
EBADINPUT 400 This means there was something wrong with the incoming request data.
EOWNER 403 The response when attempting to remove an organization owner.
EACCESS 403 This means the authenticated user lacks permission for the requested resource.
ENOUSER 404 The requested account does not exist.

Invite a Member by Email

POST /account/bigbusinessinc/invites HTTP/1.1
Host: api.pagedip.com
Authorization: Bearer API_TOKEN
Content-Type: application/json
Content-Length: 33

{
  "email": "user@example.org"
}
curl -X POST https://api.pagedip.com/account/bigbusinessinc/invites \
    -H "Authorization: Bearer API_TOKEN" \
    -d "email=user@example.org"
client.account("bigbusinessinc").invites.send("user@example.org")
  .then(function(result) {
    console.log(result);
  }).catch(function(e) {
    console.error(e);
  });

It is possible to invite a user to become a member of organization via their email. This allows users which do not yet have Pagedip accounts to create one and be automatically added to the organization. Existing users will also be added, making it easier for the organization to add a member without knowing their Pagedip username.

An invite can only be used once, by a single user.

HTTP Request

POST https://api.pagedip.com/account/:name/invites

Parameter Description
name The organizations's name to invite a user to.

Request Fields

Field Type Description
email String The email address to send the invite too. Inside will be a URL with the invite token. This email is only used to send the token, users are not required to use the email when signing up for an account.

Response Fields

{
  "ok": true,
  "email": "user@example.org",
  "type": "organization",
  "value": "bigbusinessinc",
  "from": "tyler",
  "created": "2016-03-28T19:48:31.302Z",
  "token": "cfc60fff-96d9-47c4-a8e1-1614a2656c78"
}
Field Type Description
email String The email address the invite was sent to.
type String The invite type, which will always be set to organization.
value String The organization name the invited user will be automatically added to.
from String The user that created the invitation. This is derived from the authentication token.
created String Exact moment of the invitation's creation, in the form of an ISO 8601 date string.
token String The unique invite token.

Errors

Code Status Description
ENOTORG 400 The requested account is not an organization.
EBADINPUT 400 This means there was something wrong with the incoming request data.
EACCESS 403 This means the authenticated user lacks permission for the requested resource.
ENOUSER 404 The requested account does not exist.

Revoke an Email Invitation

DELETE /account/bigbusinessinc/invites HTTP/1.1
Host: api.pagedip.com
Authorization: Bearer API_TOKEN
Content-Type: application/json
Content-Length: 53

{
  "token": "cfc60fff-96d9-47c4-a8e1-1614a2656c78"
}
curl -X DELETE https://api.pagedip.com/account/bigbusinessinc/invites \
    -H "Authorization: Bearer API_TOKEN" \
    -d "token=cfc60fff-96d9-47c4-a8e1-1614a2656c78"
client.account("bigbusinessinc").invites.revoke("cfc60fff-96d9-47c4-a8e1-1614a2656c78")
  .then(function(result) {
    console.log(result);
  }).catch(function(e) {
    console.error(e);
  });

A previously created invite can be revoked by sending a DELETE request to the invite endpoint. A revoked invite will prevent the original recipient from using it. Invites that have already been used cannot be revoked.

HTTP Request

DELETE https://api.pagedip.com/account/:name/invites

Parameter Description
name The organizations's name to remove an invite from.

Request Fields

Field Type Description
token String The invite token to revoke.

Response Fields

{
  "ok": true,
  "email": "user@example.org",
  "type": "organization",
  "value": "bigbusinessinc",
  "from": "tyler",
  "created": "2016-03-28T19:48:31.302Z",
  "token": "cfc60fff-96d9-47c4-a8e1-1614a2656c78",
  "_deleted": true
}
Field Type Description
email String The email address the invite was sent to.
type String The invite type, which will always be set to organization.
value String The organization name the invited user will be automatically added to.
from String The user that created the invitation. This is derived from the authentication token.
created String Exact moment of the invitation's creation, in the form of an ISO 8601 date string.
token String The unique invite token.
_deleted Boolean Set to true to show this invite has been revoked.

Errors

Code Status Description
ENOTORG 400 The requested account is not an organization.
EACCESS 403 This means the authenticated user lacks permission for the requested resource.
EBADINVITE 403 The invite to revoke has a mismatching 'type' field and cannot be revoked.
ENOUSER 404 The requested account does not exist.
ENOINVITE 404 The invite to revoke does not exist.

List All Email Invitations

GET /account/bigbusinessinc/invites HTTP/1.1
Host: api.pagedip.com
Authorization: Bearer API_TOKEN
curl https://api.pagedip.com/account/bigbusinessinc/invites \
    -H "Authorization: Bearer API_TOKEN"
client.account("bigbusinessinc").invites.list()
  .then(function(invites) {
    console.log(invites);
  }).catch(function(e) {
    console.error(e);
  });

Retrieve a list of all pending invites by sending a GET request to the invite endpoint. Invites that have already been used will not show up in the list.

HTTP Request

GET https://api.pagedip.com/account/:name/invites

Parameter Description
name The organizations's name to list invites for.

Response Fields

{
  "ok": true,
  "total_rows": 1,
  "rows": [
    {
      "email": "user@example.org",
      "type": "organization",
      "value": "bigbusinessinc",
      "from": "tyler",
      "created": "2016-03-28T19:38:41.001Z",
      "token": "cfc60fff-96d9-47c4-a8e1-1614a2656c78"
    }
  ]
}

The response will be a list of invite objects with the following fields:

Field Type Description
email String The email address the invite was sent to.
type String The invite type, which will always be set to organization.
value String The organization name the invited user will be automatically added to.
from String The user that created the invitation. This is derived from the authentication token.
created String Exact moment of the invitation's creation, in the form of an ISO 8601 date string.
token String The unique invite token.

Errors

Code Status Description
ENOTORG 400 The requested account is not an organization.
EACCESS 403 This means the authenticated user lacks permission for the requested resource.
ENOUSER 404 The requested account does not exist.

Custom Domains

By default, all Pagedips are accessible via the owner's personal domain name, [owner].pagedip.com. Pagedips can be made accessible by other, non-Pagedip domains by using the custom domains API. Add DNS records pointing to the owner URL, then add the domain using this API so Pagedip displays the correct content for that domain.

Custom domains can be pointed at one of two items:

List all Custom Domains

Account Domains:

GET /domains/tyler HTTP/1.1
Host: api.pagedip.com
Authorization: Bearer API_TOKEN
curl https://api.pagedip.com/domains/tyler \
  -H "Authorization: Bearer API_TOKEN"
client.account("tyler").domains.list()
  .then(function(domains) {
    console.log(domains);
  })
  .catch(function(e) {
    console.error(e);
  });

Pagedip Domains:

GET /domains/tyler/notes HTTP/1.1
Host: api.pagedip.com
Authorization: Bearer API_TOKEN
curl https://api.pagedip.com/domains/tyler/notes \
  -H "Authorization: Bearer API_TOKEN"
client.pagedip("tyler", "notes").domains.list()
  .then(function(domains) {
    console.log(domains);
  })
  .catch(function(e) {
    console.error(e);
  });

List all the domains pointing at an account or Pagedip using the /domains endpoint.

HTTP Request

GET /domains/:name
GET /domains/:owner/:handle

Parameter Description
name The user or organization name to get domains for.
owner The user or organization name for the owner of a Pagedip.
handle The unique Pagedip handle.

Response Fields

{
  "ok": true,
  "total_rows": 1,
  "rows": [
    {
      "domain": "customdomain.com",
      "created": "2016-03-21T23:34:26.832Z"
    }
  ]
}

The response will be a list of domain objects with the following fields:

Field Type Description
domain String A domain name pointing the resource.
created String The date and time this domain was added as an ISO 8601 date string.

Errors

Code Status Description
ENOUSER 404 The requested account does not exist.
ENOPAGEDIP 404 The requested pagedip does not exist.

Add a Custom Domain

Account Domains:

PUT /domains/tyler HTTP/1.1
Host: api.pagedip.com
Authorization: Bearer API_TOKEN
Content-Type: application/json
Content-Length: 34

{
  "domain": "customdomain.com"
}
curl -X PUT https://api.pagedip.com/domains/tyler \
  -H "Authorization: Bearer API_TOKEN" \
  -d "domain=customdomain.com"
client.account("tyler").domains.add("customdomain.com")
  .then(function(result) {
    console.log(result);
  })
  .catch(function(e) {
    console.error(e);
  });

Pagedip Domains:

PUT /domains/tyler/notes HTTP/1.1
Host: api.pagedip.com
Authorization: Bearer API_TOKEN
Content-Type: application/json
Content-Length: 34

{
  "domain": "customdomain.com"
}
curl -X PUT https://api.pagedip.com/domains/tyler/notes \
  -H "Authorization: Bearer API_TOKEN" \
  -d "domain=customdomain.com"
client.pagedip("tyler", "notes").domains.add("customdomain.com")
  .then(function(domains) {
    console.log(domains);
  })
  .catch(function(e) {
    console.error(e);
  });

Point a custom domain to a Pagedip or account by sending a PUT request to the /domains endpoint. Domains are validated against RFC 1035 and must contain at least a TLD and a root domain.

HTTP Request

PUT /domains/:name
PUT /domains/:owner/:handle

Parameter Description
name The user or organization name to add domains to.
owner The user or organization name for the owner of a Pagedip.
handle The unique Pagedip handle.

Request Fields

Field Type Description
domain String A custom domain name to add.

Response Fields

{
  "ok": true,
  "domain": "customdomain.com",
  "created": "2016-03-21T23:34:26.832Z"
}
Field Type Description
domain String The domain name that was just added.
created String The date and time this domain was added as an ISO 8601 date string.

Errors

Code Status Description
EBADINPUT 400 This means there was something wrong with the incoming request data.
ENOUSER 404 The requested account does not exist.
ENOPAGEDIP 404 The requested pagedip does not exist.
EEXISTS 409 The domain already exists in the Pagedip ecosystem, possibly on a different Pagedip or account.

Remove a Custom Domain

Account Domains:

DELETE /domains/tyler HTTP/1.1
Host: api.pagedip.com
Authorization: Bearer API_TOKEN
Content-Type: application/json
Content-Length: 34

{
  "domain": "customdomain.com"
}
curl -X DELETE https://api.pagedip.com/domains/tyler \
  -H "Authorization: Bearer API_TOKEN" \
  -d "domain=customdomain.com"
client.account("tyler").domains.remove("customdomain.com")
  .then(function(result) {
    console.log(result);
  })
  .catch(function(e) {
    console.error(e);
  });

Pagedip Domains:

DELETE /domains/tyler/notes HTTP/1.1
Host: api.pagedip.com
Authorization: Bearer API_TOKEN
Content-Type: application/json
Content-Length: 34

{
  "domain": "customdomain.com"
}
curl -X DELETE https://api.pagedip.com/domains/tyler/notes \
  -H "Authorization: Bearer API_TOKEN" \
  -d "domain=customdomain.com"
client.pagedip("tyler", "notes").domains.remove("customdomain.com")
  .then(function(domains) {
    console.log(domains);
  })
  .catch(function(e) {
    console.error(e);
  });

Remove a custom domain that was previously added by sending a DELETE request to the /domain endpoint.

HTTP Request

DELETE /domains/:name
DELETE /domains/:owner/:handle

Parameter Description
name The user or organization name to remove domains from.
owner The user or organization name for the owner of a Pagedip.
handle The unique Pagedip handle.

Request Fields

Field Type Description
domain String A custom domain name to remove.

Response Fields

{
  "ok": true,
  "domain": "customdomain.com",
  "created": "2016-03-21T23:34:26.832Z"
}
Field Type Description
domain String The domain name that was just removed.
created String The date and time this domain was originally added as an ISO 8601 date string.

Errors

Code Status Description
EBADINPUT 400 This means there was something wrong with the incoming request data.
ENOUSER 404 The requested account does not exist.
ENOPAGEDIP 404 The requested pagedip does not exist.
ENODOMAIN 404 The domain does not exist or is pointing to a different account or Pagedip.

Errors

{
  "error": true,
  "message": "Invalid session.",
  "status": 401,
  "code": "EBADSESSION"
}

These are common error response codes. There are other error codes returned by specific endpoints that are not listed here.

Code Status Description
EBADINPUT 400 This means there was something wrong with the incoming request data.
EBADTOKEN 401 The API token was missing or invalid.
EBADSESSION 401 The API token session no longer exists, usually as a result of signing out. A brand new token must be created using a username and password.
EEXPTOKEN 401 This API token has expired and is no longer valid. Renew the token to obtain a new valid token.
EACCESS 403 This means the authenticated user lacks permission for the requested resource.
ENOUSER 404 Requested user does not exist.
EEXISTS 409 Returned when the requested resource already exists.
EERROR 500 Internal Server Error.