Introduction

Welcome to the reference for the Quire REST API!

The Quire REST API provides a broad set of operations and resources that:

• Consistently do repetitive or tedious tasks.
• Chain a process together for your team’s process and workflow.
  • Pull information from other locations such as email and Evernote into Quire.
  • Push information from Quire to other locations such as email and Zapier.

Want to share your thoughts on how Quire API works for you? Tell us how you feel about using our API and what we can do to make it better.

REST is a web-service protocol for rapid development by using HTTP and JSON technology.

API Changelog

You can find the Changelog of the API Reference in the Quire Community.

Authentication

For full setup instructions, see our Complete Setup Guide on the Quire blog.

OAuth v2.0

Quire uses OAuth v2.0 to authenticate your app and access the Quire REST API on a user’s behalf—without requiring the user’s password.

Authenticating via OAuth2 requires the following steps:

1. Register Your Application on Quire
2. Ask a Quire User to Grant Access to Your Application
3. Retrieve an Access Token
4. Make Authenticated Requests

Register Your Application on Quire

1. Give your app a cool name

Your app deserves a cool name that lives up to its broad range of great features.

All of the app users will see this name in public, so think carefully!

2. Choose the Quire Organization that your app belongs to

You can choose an organization in Quire that your app belongs to.

If one day you decide to leave the organization, you will lose the authority to manage the app.

3. Redirect URL

When users grant your app authorization request, users will be directed to the configured URL that you’ve set.

4. Choose permission scopes

You can set permission on what your app can do with Quire. There are several options for you to choose from.

Note: If none of the options is selected, the app can only read user’s data.

5. Development Client ID and Client Secret

The Client ID and Client secret will be automatically generated as you create an app.

The Client ID is a unique ID to identify your app.

You should keep your client secret safe, which means you should never share your client secret with anyone. If you choose to regenerate the client secret, the old one will immediately become invalid.

6. Update your App

If your app hasn't been published to Quire App Directory, it will remain as unpublished status. You can still use the configured shareable link in the Developer App Console Distribution to share the app with other users for testing or integration.

When you make changes to the app, you can use the shareable link to access the development copy as well. Working on your development copy will not affect your live App Directory app. When your updated app is ready to be published and replaced the old version on Quire App Directory, your published app will have a different Client ID to the unpublished one.

There are two sets of Client ID and Client Secret.

• Development set - should be used during developing and testing internally of the app.
• Production set - should be used once your app is ready and published on Quire App Directory.

Fulfill Authorization Request

Ask a Quire User to Grant Access to Your Application

Once registering your application, you can ask your user to grant access to your application.

The authorization endpoint lets users grant your app access to the requested permissions.

The authorization endpoint should look like this:

https://quire.io/oauth?client_id=your-client-ID&redirect_uri=your-redirect-uri

After your user clicks Allow, the access will be granted, and he will be redirected to the URL you specified in the redirect_uri parameter with an authorization code provided as a query parameter called code.

After your app is granted, you can have an authorization code to exchange access token for access Quire API. The redirect_uri is optional. If not being specified, we will automatically use the one that is previously detected in the app. If specified, the redirect URL must start with the prefix of the one that was previously detected in the app.

Parameter	Value
client_id	{your-client-ID}
redirect_uri	Optional. The redirect URL after granted. If specified, it must match the redirect URL specified in your app's config. Otherwise, the configured URL will be used.
state	Optional. A random string generated by your app to protect from XSRF.

Retrieve Access Token

To retrieve the access token, you have to post a request to https://quire.io/oauth/token with the following data:

Parameter	Value
grant_type	authorization_code
code	{your-authorization-code}
client_id	{your-client-ID}
client_secret	{your-client-secret}

curl -X POST \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code&code=Your_code_from_previous_step&client_id=Your_app_client_id&client_secret=Your_app_client_secret" \
  https://quire.io/oauth/token

Then, the access token will be returned in the response's body.

{
  "access_token":"ACCESS_TOKEN",
  "token_type": "bearer",
  "expires_in":2592000,
  "refresh_token":"REFRESH_TOKEN"
}

The token should be kept carefully and permanently since you need it to access every Quire API.

PKCE Support

Quire supports PKCE (RFC 7636) for public clients such as single-page apps. To use it:

1. Add code_challenge and code_challenge_method=S256 to the authorization request.
2. Send code_verifier instead of client_secret when exchanging the authorization code for a token.

Note: Only S256 is supported. PKCE tokens do not include a refresh_token.

Use Access Token to Access Quire API

In each request, the access token must be put in the header. The header name is Authorization and the value is Bearer your_token.

After you exchange the access token, your app can make requests to Quire API on behalf of the authorized users.

curl -H 'Authorization: Bearer {access_token}' \
https://quire.io/api/user/id/me

{
  "email": "john@gmail.cc",
  "website": "https://coolwebsites.com",
  "id": "My_ID",
  "description": "This is *cool*!",
  "url": "https://quire.io/u/My_ID",
  "nameText": "My Name",
  "nameHtml": "My Name",
  "descriptionText": "This is cool!",
  "descriptionHtml": "This is <i>cool</i>!",
  "image": "https://quire.s3.amazonaws.com/oid/image.jpg",
  "iconColor": "37",
  "name": "My Name",
  "oid": "Dyh2YkFcu9uLgLFIeN1kB4Ld"
}

Token Expiration

A refresh token might stop working for one of these reasons:

• The user has revoked your app's access.
• The refresh token has not been used for 6 months.

Publish App

By default, your app will be set as Private. You can change the app distribution to Public so that other Quire users can install your app to their workspace as well.

If your app is made available on Quire App Directory and you want to delete the app, you should communicate with your users first before depreciating the app.

WebHook

When one event on Quire is triggered, the system will send a payload to the webhook's configured URL.

A webhook is used by Quire to call an app, while Quire API is used by an app to call Quire. To receive these events, you have to specify a valid URL for Webhooks when configuring your app.

For a complete guide, see our blog post.

System Events

A system event is used to notify your app about system or app's activities.

Token Expiration

When the token has been expired or revoked, an event will be sent to your app. You can clean up your storage if necessary.

{
  "type": "system",
  "token": "hook-token-defined-by-you",
  "secret": "secret-defined-by-you",
  "data": {
    "type": "token-revocation",
    "token": "the-refresh-token"
  }
}

Host Revocation

When the user revokes the grant to a host (either a project or an organization), an event will be sent to your app. You can clean up your storage if necessary.

{
  "type": "system",
  "token": "hook-token-defined-by-you",
  "secret": "secret-defined-by-you",
  "data": {
    "type": "host-revocation",
    "token": "the-refresh-token",
    "host": "host-oid",
    "otype": "host-type",
  }
}

Notification Events

A notification is the information about an update (aka., an activity). Here is an example:

{
  "type": "notification",
  "token": "hook-token-defined-by-you",
  "secret": "secret-defined-by-you",
  "projectSummary": {
    "oid": "project-oid-where-event-occurred",
    "id": "project-id"
  },
  "organizationSummary": {
    "oid": "organization-where-event-occurred",
    "id": "organization-id"
  },
  "data": {
    "type": 0, //activity's type
    "when": "2019-09-30T08:20:12.000Z",
    "what": {
      "oid": "YxjapXXRCOYxoaiCT4tT3OQm", //OID of a task, project, or organization depending on type
      "id": 101,
      "name": "Brand new start",
      "parent": {
        "oid": "parent-oid",
        "id": "parent-id",
        "parent": {
          "oid": "grand-parent-oid",
          "id": "grand-parent-id",
        }
      }
    },
    "user": {
      "oid": "1AbDEFed2A5031BEDDweqmde", //OID of the user
      "id": "john.doer",
      "name": "John Doer"
    },
    "message": "<a href=\"https://quire.io/u/john.doer\">John Doer</a> added <a href=\"https://quire.io/w/MyProjects/101\">Brand new start</a>",
    "text": "John Doer added Brand new start",
    "url": "https://quire.io/w/MyProjects/101"
  } 
}

• The data map may also include an optional value field, which provides detailed information as a map. For example, for an assignment notification, value includes the assignee’s ID, name, and URL.

• If the notification is about a start or due change, the data map will include an additional due field. This value is a date/time formatted in the user’s locale and time zone.

• If the event notifies a task update and the task has a parent, the parent information is included in the parent field. The parent field is a map containing the task’s oid and id. If the task’s parent also has a parent, the map includes a nested parent field as well.

• The projectSummary and organizationSummary fields provide information about the project and organization where the event occurred.

• There is an additional field, taskSummaries, for activities that can affect multiple tasks (for example, removing a task that has subtasks). This field is a list of map instances. Each map represents a task that was changed. If any of that task's subtasks were also changed, they are included in the map’s tasks field.

  • Please refer to Activity Types | taskSummaries.

Registration for Notifications

For instructions on updating a project, see Update a project by OID.

If the app wants to receive notifications of a specific projects or tasks, it can follow the projects or apps by sending a PUT request to the URL. To add a follower, the body of the request can be:

Syntax 1

{
  "addFollowers": ["app"]
}

where app is a keyword. It indicates that the app would like to receives the notifications about the given target (a project or a task). That is, it'll add the app into the target's followers.

Syntax 2

In additions, you can specify additional information that will be passed as part of a notification in the following syntax.

"app|team|channel"

where app is a keyword while team and channel are application specific. That is, you can pass any value to team and channel.

Note: team and channel can not contain '|'.

For example,

{
  "addFollowers": ["app|extra101"]
}

Then, the notification will carry additional field called team with the value "extra101":

{
  "type": "notification",
  "team": "extra101",
  "data": {
    //refer the Notifications section for details
  }
}

Another example:

{
  "addFollowers": ["app|extra101|channel9"]
}

You'll get:

{
  "type": "notification",
  "team": "extra101",
  "channel": "channel9",
  "data": {
    //refer the Notifications section for details
  }
}

Syntax 3

"app|team|channel|mine"

where both app and mine are keywords. It is similar to Syntax 2, except it receives only notifications that match the notification setting of the user.

If you don't need both team and channel, you can specify: "app|||mine.

The notification setting can be found at https://quire.io/w/YourProject?view=setting&tab=options#notifications

Syntax 4

"app|/path"

where app is a keyword, and /path is application specific. The path will be appended to the app's hook URL. For example, assume the app's hook URL is "https://super.app/hooks/standard", and the follower "app|/soc/id279/channel51". Then, the notification will be posted the following URL: "https://super.app/hooks/standard/soc/id279/channel51".

Syntax 5

If you'd like to pass additional information in this syntax, you can append it as follows.

"app|/path|channel"

For example, app|/soc/id8|box51. Then, box51 will be part of the JSON object sent to the hook URL.

{
  "type": "notification",
  "channel": "box51",
  "data": {
    //refer the Notifications section for details
  }
}

Responding and Retries

When receiving the notification, your Web Hook shall return a status code between 200 and 299 to indicate success.

If a status code other than above is returned, we will retry 15 minutes later, then 1 hour later and 1 day later.

Activities Types

• Activity Types

Rate Limits

To protect the stability of the API and keep it available to all users, Quire enforces multiple kinds of rate limiting. Requests that hit any of our rate limits will receive a 429 Too Many Requests response. We may change these quotas or add new quotas in the future.

Here are the limits for free plans.

Plan	Maximum requests per organization, per minute	Maximum requests per organization, per hour
Free	25	120

Note: the limit is per-organization. It sums up the total number of all accesses from all applications for each organization. For more quota, please refer to Pricing.

When a rate limit is exceeded, the response includes a standard Retry-After header whose value is the number of seconds to wait before retrying. The value reflects the time until the offending per-minute or per-hour counter resets, so clients can back off precisely instead of guessing.

HTTP/1.1 429 Too Many Requests
            Retry-After: 37
            Content-Type: application/json
            
            {"code": 429, "message": "..."}
            

Size limits

The size of each request can't be larger than 1MB. Requests that hit this limit will receive a 413 Content too large response.

Status Codes

Code	Meaning	Description
200	Success	Request successful
400	Bad Request	You're using a wrong parameter, or passing incorrect data.
401	Unauthorized	Invalid or expired token.
402	Payment required	The organization’s subscription does not permit use of this app.
403	Forbidden	Not authorized to access the resource.
404	Not Found	The specified resource could not be found.
405	Method not allowed	Method not allowed or supported.
409	Conflict	There is already a resource with the same criteria.
413	Content too large	The request's content is larger than 1MB.
418	Not valid JSON content	The request's content doesn't appear to be JSON.
429	Too Many Requests	Exceeded the rate limit for API calls
500	Internal Server Error	There is an unexpected error.
503	Service Unavailable	Server is down for maintenance.

Error Responses

The following JSON data is returned in the response body when an error occurs.

{
    "code": a_number,
  "message": "an error message here"
}

Error Code	Meaning
100	General authentication error.
400	Bad request including wrong request body, wrong parameter and so on.
401	Invalid or expired token.
403	Forbidden.
404	Resource not found.
405	Method not allowed.
413	Request too large.
429	Too many invocations.
469	Quota exceeded, such as number of projects and number of members.
500	General invocation error. Most likely, an internal error.

https://quire.io/api