API Documentation

Overview

The Siasto API gives you programmatic access to all of the people, teams, projects, and other resources associated with your Siasto account. You can use it to augment an existing applications, or even to build your own applications from scratch.

The Siasto API is organized around REST, and provides predictable, resource-oriented URLs. It also uses built-in HTTP features (e.g. HTTP authentication and HTTP verbs) supported by generic HTTP clients.

Lastly, the Siasto API accepts input via JSON or form-encoded content in your requests, and always returns JSON content in its responses.

Authentication

All API requests must be made over HTTPS. Requests made over plain HTTP will fail.

The Siasto API uses HTTP Basic Auth for authentication, with your API key as the username. The password should be left blank. You must authenticate for all requests.

To find your API key, log into Siasto and come back to this page.

Errors

Error Codes

When a failure occurs, the Siasto API should return an HTTP Status Code indicating the nature of the failure, with a response body containing additional information under the "errors" key.

  • 200 Success The request succeeded. Any data returned will be available via the "data" key in the top-level of the JSON response.
  • 201 Success Object creation succeeded. The object's data will be available via the "data" key in the top-level of the JSON response. The API URL where the object can be retrieved is also returned in the Location header of the response.
  • 400 Bad Request Usually a result of a missing or malformed parameter.
  • 401 Unauthorized No valid API key provided.
  • 402 Request Failed Parameters were valid but request failed.
  • 403 Forbidden Everything was valid, however the request was not allowed, likely because it attempted to access (or make changes to) a resource that the user doesn't have access to.
  • 404 Not Found The requested item doesn't exist.
  • 500 Server Error Something went wrong on our end.

Example Errors

HTTP/1.1 401 { "errors": [ { "message": "Not Authorized" } ] } HTTP/1.1 403 { "errors": [ { "message": "You don't have permission to access this." } ] } HTTP/1.1 500 { "errors": [ { "message": "Siasto encountered a server error." } ] }

Pagination

By default, requests for a list of resources will return all such resources. However, the Siasto API also supports pagination via the following parameters:

limit integer

The maximum number of results you'd like returned. For example, 50. Defaults to infinity.

offset integer

The number of records to skip before returning results. For example, 10. Defaults to 0.

Users

THE USER OBJECT

A user object represents an account in Siasto and includes the following fields:

id string

The unique identifier for the user. For example, usr_1a2b3c4d.

email string

The user's email address. For example, user@example.com.

name string

The user's name. For example, Courtland Allen.

avatar_url string

The URL at which the user's avatar is located. For example, https://www.example.com/image.png.

date_created string

The date and time the user joined Siasto in ISO 8601 format. For example, 2014-04-22T04:32:00+0000.

RETRIEVING A USER

GET /users/{USER_ID}

Example Request

curl https://www.siasto.com/api/v2/users/{USER_ID} \ -u {YOUR_API_KEY}:

Example Response

{ "data": { "id": "usr_1a2b3c4d", "email": "courtland@example.com", "name": "Courtland Allen", "avatar_url": "https://www.example.com/image.png", "date_created": "2014-04-22T04:32:00+0000", } }

RETRIEVING MULTIPLE USERS

GET /users GET /teams/{TEAM_ID}/users GET /projects/{PROJECT_ID}/users

Example Request

curl https://www.siasto.com/api/v2/users \ -u {YOUR_API_KEY}:

Example Response

{ "data": [ { "id": "usr_1a2b3c4d", "email": "courtland@example.com", "name": "Courtland Allen", "avatar_url": "https://www.example.com/image.png", "date_created": "2014-04-22T04:32:00+0000", }, ... ] }

UPDATING THE USER'S ACCOUNT

PUT /users/{USER_ID}

Note that the user ID specified must belong to the authenticated user, or this request will return a 403 Forbidden error. (A user is only allowed to update his own account.)

You should specify at least one of the following parameters:

name optional

The user's name. For example, Courtland Allen.

avatar_url optional

The URL at which the user's avatar is located. For example, https://www.example.com/image.png.

Example Request

curl https://www.siasto.com/api/v2/users/{USER_ID} \ -u {YOUR_API_KEY}: \ -X PUT \ -d "name=Totally New Name" \ -d "avatar_url=https://www.example.com/new.png"

Example Response

{ "data": { "id": "usr_1a2b3c4d", "email": "courtland@example.com", "name": "Totally New Name", "avatar_url": "https://www.example.com/new.png", "date_created": "2014-04-22T04:32:00+0000", } }

TEAMS

THE TEAM OBJECT

Teams are the highest level of organization within Siasto. A team object represents a collection of people and the projects they're working on:

id string

The unique identifier for the task. For example, wkp_1a2b3c4d.

name string

The name of the team. For example, Tyrant, Inc..

role string

The user's role with the team. Either guest, member, or admin.

user_ids array

An array of strings representing the IDs of users who have access to the team. For example, ["usr_1a2b3c4d", "usr_5e6f7g8h", ...].

date_created string

The date and time the team was created in ISO 8601 format. For example, 2014-04-22T04:32:00+0000.

RETRIEVING A TEAM

GET /teams/{TEAM_ID}

Example Request

curl https://www.siasto.com/api/v2/teams/{TEAM_ID} \ -u {YOUR_API_KEY}:

Example Response

{ "data": { "id": "wkp_1a2b3c4d", "name": "Tyrant, Inc.", "role": "admin", "user_ids": ["usr_1a2b3c4d", "usr_5e6f7g8h"], "date_created": "2014-04-22T04:32:00+0000", } }

RETRIEVING MULTIPLE TEAMS

GET /teams

Example Request

curl https://www.siasto.com/api/v2/teams \ -u {YOUR_API_KEY}:

Example Response

{ "data": [ { "id": "wkp_1a2b3c4d", "name": "Tyrant, Inc.", "role": "admin", "user_ids": ["usr_1a2b3c4d", "usr_5e6f7g8h"], "date_created": "2014-04-22T04:32:00+0000", }, ... ] }

UPDATING A TEAM

PUT /teams/{TEAM_ID}

Note that if the user is not an administrator within the specified team, this request will return a 403 Forbidden error.

There's only one attribute that can be changed:

name optional

The name of the team. For example, Tyrant, Inc..

Example Request

curl https://www.siasto.com/api/v2/teams/{TEAM_ID} \ -u {YOUR_API_KEY}: \ -X PUT \ -d "name=New Team Name"

Example Response

{ "data": { "id": "wkp_1a2b3c4d", "name": "New Team Name", "role": "admin", "user_ids": ["usr_1a2b3c4d", "usr_5e6f7g8h"], "date_created": "2014-04-22T04:32:00+0000", } }

PROJECTS

THE PROJECT OBJECT

Projects are the second-highest level of organization Project represents a collection of people, files, tasks, events, and discussions.

id string

The unique identifier for the project. For example, prj_1a2b3c4d.

name string

The name of the project. For example, Company Website.

description string or null

An optional description of the project. For example, Finish the official company website..

user_ids array

An array of strings representing the IDs of users who have access to the project. For example, ["usr_1a2b3c4d", "usr_5e6f7g8h", ...].

team_id string

The unique identifier of the team the project belongs to. For example, wkp_1a2b3c4d.

date_completed string or null

The date and time the project was completed in ISO 8601 format. For example, wkp_1a2b3c4d. If the project has not been completed, this field will be null.

date_created string

The date and time the project was created in ISO 8601 format. For example, 2014-04-22T04:32:00+0000.

RETRIEVING A PROJECT

GET /projects/{PROJECT_ID}

Example Request

curl https://www.siasto.com/api/v2/projects/{PROJECT_ID} \ -u {YOUR_API_KEY}:

Example Response

{ "data": { "id": "prj_1a2b3c4d", "name": "Company Website", "description": "Finish the official company website.", "user_ids": ["usr_1a2b3c4d", "usr_5e6f7g8h"], "team_id": "wkp_1a2b3c4d", "date_completed": null, "date_created": "2014-04-22T04:32:00+0000", } }

RETRIEVING MULTIPLE PROJECTS

GET /projects GET /teams/{TEAM_ID}/projects

Example Request

curl https://www.siasto.com/api/v2/projects \ -u {YOUR_API_KEY}:

Example Response

{ "data": [ { "id": "prj_1a2b3c4d", "name": "Company Website", "description": "Finish the official company website.", "user_ids": ["usr_1a2b3c4d", "usr_5e6f7g8h"], "team_id": "wkp_1a2b3c4d", "date_completed": null, "date_created": "2014-04-22T04:32:00+0000", }, ... ] }

CREATING A NEW PROJECT

POST /projects POST /teams/{TEAM_ID}/projects

Your request may include the following parameters:

name required

The name of the project. For example, Company Website.

user_ids required

An array of IDs for users who should be a part of the project. For example, [usr_1a2b3c4d, usr_5e6f7g8h, ...]. Users must be a part of the same team the project is in. Also, the authenticated user + all administrators from the team will automatically be added to the project whether or not they are included here.

description optional

An optional description of the project. For example, Finish the official company website..

team_id required

The unique identifier of the team the project belongs to. For example, wkp_1a2b3c4d.

Example Request

curl https://www.siasto.com/api/v2/projects \ -u {YOUR_API_KEY}: \ -X POST \ -d "name=New Project" \ -d "user_ids[]=usr_1a2b3c4d" \ -d "user_ids[]=usr_5e6f7g8h" \ -d 'description=This is important!' \ -d "team_id=wkp_1a2b3c4d"

Example Response

{ "data": { "id": "prj_1a2b3c4d", "name": "New Project", "description": "This is important!", "user_ids": ["usr_1a2b3c4d", "usr_5e6f7g8h"], "team_id": "wkp_1a2b3c4d", "date_completed": null, "date_created": "2014-04-22T04:32:00+0000", } }

UPDATING A PROJECT

PUT /projects/{PROJECT_ID}

You should specify at least one of the following parameters:

name required

The name of the project. For example, Company Website.

description optional

An optional description of the project. For example, Finish the official company website.. Leave blank to erase the project's description.

completed optional

Specify true to mark the project as complete, or false to mark it as incomplete (ongoing).

Example Request

curl https://www.siasto.com/api/v2/projects/{PROJECT_ID} \ -u {YOUR_API_KEY}: \ -X PUT \ -d "name=New Name" \ -d "description=" \ -d "completed=true" \ -d "team_id=wkp_1a2b3c4d"

Example Response

{ "data": { "id": "prj_1a2b3c4d", "name": "New Name", "description": null, "user_ids": ["usr_1a2b3c4d", "usr_5e6f7g8h"], "team_id": "wkp_1a2b3c4d", "date_completed": "2014-04-22T04:32:00+0000", "date_created": "2014-04-22T04:32:00+0000", } }

DELETING A PROJECT

DELETE /projects/{PROJECT_ID}

Note that if the user only has guest-level access to the project's team, this request will return a 403 Forbidden error, as guests do not have permission to delete projects.

Example Request

curl https://www.siasto.com/api/v2/projects/{PROJECT_ID} \ -u {YOUR_API_KEY}: \ -X DELETE

Example Response

{ "data": { "success": true, "message": "The project has been deleted." } }

TASKS

THE TASK OBJECT

Tasks are the basic unit of work in Siasto. They let you know what's being done, when, and by whom. All task objects are associated with a single project and are assigned to at least one user.

id string

Uniq Iden tsk_1a2b3c4d.

name string

The name of the task. For example, attach covers to TPS reports..

description string or null

An optional description for the task. For example, please use the new coversheets for this.

assignee_ids array

An array of strings representing the IDs of users who are assigned to the task. For example, ["usr_1a2b3c4d", "usr_5e6f7g8h", ...].

tags array

An array of strings representing tags that apply to the task. For example, ["coding", "blog", "design", ...].

project_id string

The unique identifier of the project the task belongs to. For example, prj_1a2b3c4d.

parent_task_id string or null

The unique identifier of the task's parent task if it has one. For example, tsk_1a2b3c4d.

discussion_id string or null

The unique identifier of the discussion about this task if one exists. For example, dsc_1a2b3c4d.

date_due string or null

The date and time the task is due in ISO 8601 format. For example, 2014-04-22T04:32:00+0000. If the task does not have a due date, this attribute will be null.

date_completed string or null

The date and time the task was completed in ISO 8601 format. For example, attach covers to TPS reports.. the task has not been completed, this attribute will be null.

date_created string

The date and time the task was created in ISO 8601 format. For example, 2014-04-22T04:32:00+0000.

RETRIEVING A TASK

GET /tasks/{TASK_ID}

Example Request

curl https://www.siasto.com/api/v2/tasks/{TASK_ID} \ -u {YOUR_API_KEY}:

Example Response

{ "data": { "id": "tsk_1a2b3c4d", "name": "attach covers to TPS reports", "description": "please use the new coversheets for this", "assignee_ids": ["usr_1a2b3c4d", "usr_5e6f7g8h"], "tags": ["terrible ideas", "ugh"], "project_id": "prj_1a2b3c4d", "parent_task_id": null, "discussion_id": null, "date_due": "2014-04-22T04:32:00+0000", "date_completed": null, "date_created": "2014-04-22T04:32:00+0000", } }

RETRIEVING MULTIPLE TASKS

GET /tasks GET /teams/{TEAM_ID}/tasks GET /projects/{PROJECT_ID}/tasks

Example Request

curl https://www.siasto.com/api/v2/tasks \ -u {YOUR_API_KEY}:

Example Response

{ "data": [ { "id": "tsk_1a2b3c4d", "name": "attach covers to TPS reports", "description": "please use the new coversheets for this", "assignee_ids": ["usr_1a2b3c4d", "usr_5e6f7g8h"], "tags": ["terrible ideas", "ugh"], "project_id": "prj_1a2b3c4d", "parent_task_id": null, "discussion_id": null, "date_due": "2014-04-22T04:32:00+0000", "date_completed": null, "date_created": "2014-04-22T04:32:00+0000", }, ... ] }

CREATING A NEW TASK

POST /tasks POST /projects/{PROJECT_ID}/tasks

Your request may include the following parameters:

name required

The name of the task. For example, attach covers to TPS reports..

description optional

An optional description for the task. For example, please use the new coversheets for this.

assignee_ids required

An array of strings representing the IDs of users who are assigned to the task. For example, ["usr_1a2b3c4d", "usr_5e6f7g8h", ...]. Tasks must have at least one assignee, and all assignees must have access to the task's parent project.

tags optional

An array of strings representing tags that apply to the task. For example, ["coding", "blog", "design", ...].

project_id required

The unique identifier of the project the task belongs to. For example, prj_1a2b3c4d.

parent_task_id optional

The unique identifier of the task's parent task if it has one. For example, tsk_1a2b3c4d.

date_due optional

The date and time the task is due in ISO 8601 format. For example, 2014-04-22T04:32:00+0000. If the task does not have a due date, this attribute will be null.

Example Request

curl https://www.siasto.com/api/v2/tasks \ -u {YOUR_API_KEY}: \ -X POST \ -d "name=attach covers to TPS reports" \ -d "description=please use the new coversheets for this" \ -d "assignee_ids[]=usr_1a2b3c4d" \ -d "assignee_ids[]=usr_5e6f7g8h" \ -d "tags[]=terrible ideas" \ -d "tags[]=ugh" \ -d "project_id=prj_1a2b3c4d" \ -d "parent_task_id=tsk_1a2b3c4d" \ -d "date_due=2014-04-22T04:32:00+0000"

Example Response

{ "data": { "id": "tsk_1a2b3c4d", "name": "attach covers to TPS reports", "description": "please use the new coversheets for this", "assignee_ids": ["usr_1a2b3c4d", "usr_5e6f7g8h"], "tags": ["terrible ideas", "ugh"], "project_id": "prj_1a2b3c4d", "parent_task_id": "tsk_1a2b3c4d", "discussion_id": null, "date_due": "2014-04-22T04:32:00+0000", "date_completed": null, "date_created": "2014-04-22T04:32:00+0000", } }

UPDATING A TASK

PUT /tasks/{TASK_ID}

The following attributes can be updated:

name optional

The name of the task. For example, attach covers to TPS reports..

description optional

An optional description for the task. For example, please use the new coversheets for this.

assignee_ids optional

An array of strings representing the IDs of users who are assigned to the task. For example, ["usr_1a2b3c4d", "usr_5e6f7g8h", ...]. Any user whose ID is present will be assigned to the task, and any whose ID is missing will be removed from the task. Note that all tasks must have at least one assignee, and all assignees must have access to the task's parent project.

tags optional

An array of strings representing tags that apply to the task. For example, ["coding", "blog", "design", ...]. Any tag that belongs to the task but is not specified in this array will be removed from the task.

project_id optional

The unique identifier of the project the task belongs to. For example, prj_1a2b3c4d.

parent_task_id optional

The unique identifier of the task's parent task if it has one. For example, tsk_1a2b3c4d. Leave blank to move the task to the top-level.

date_due optional

The date and time the task is due in ISO 8601 format. For example, 2014-04-22T04:32:00+0000. Leave bank to remove the task's due date.

completed optional

Specify true to mark the task as complete, or any other string (e.g. false) to mark it as incomplete (ongoing).

Example Request

curl https://www.siasto.com/api/v2/tasks/{TASK_ID} \ -u {YOUR_API_KEY}: \ -X PUT \ -d "assignee_ids=usr_9i10j11k" \ -d "completed=true

Example Response

{ "data": { "id": "tsk_1a2b3c4d", "name": "attach covers to TPS reports", "description": "please use the new coversheets for this", "assignee_ids": ["usr_9i10j11k"], "tags": ["terrible ideas", "ugh"], "project_id": "prj_1a2b3c4d", "parent_task_id": "tsk_1a2b3c4d", "discussion_id": null, "date_due": "2014-04-22T04:32:00+0000", "date_completed": "2014-04-22T04:32:00+0000", "date_created": "2014-04-22T04:32:00+0000", } }

DELETING A TASK

DELETE /tasks/{TASK_ID}

Example Request

curl https://www.siasto.com/api/v2/tasks/{TASK_ID} \ -u {YOUR_API_KEY}: \ -X DELETE

Example Response

{ "data": { "success": true, "message": "The task has been deleted." } }

COMMENTING ON A TASK

POST /tasks/{TASK_ID}/comments

Include the following parameter:

comment required

The text of the comment. For example, Running late, but should finish today...

Example Request

curl https://www.siasto.com/api/v2/tasks/{TASK_ID}/comments \ -u {YOUR_API_KEY}: \ -X POST \ -d "comment=Running late, but should finish today."

Example Response

{ "data": { "success": true, "message": "The comment has been posted." } }

FILES

File Object

File objects can represent anything from text documents and spreadsheets to MP3s and videos. Currently file management via the API is relatively limited, but we plan to make it a lot more powerful in future iterations.

id string

The unique identifier for the file. For example, doc_1a2b3c4d.

name string

The name of the file. For example, TPS Report.

project_id string

The unique identifier of the project the file belongs to. For example, prj_1a2b3c4d.

date_created string

The date and time the file was created in ISO 8601 format. For example, 2014-04-22T04:32:00+0000.

RETRIEVING A FILE

GET /files/{FILE_ID}

Example Request

curl https://www.siasto.com/api/v2/files/{FILE_ID} \ -u {YOUR_API_KEY}:

Example Response

{ "data": { "id": "doc_1a2b3c4d", "name": "TPS Report", "project_id": "prj_1a2b3c4d", "date_created": "2014-04-22T04:32:00+0000", } }

RETRIEVING MULTIPLE FILES

GET /files GET /projects/{PROJECT_ID}/files GET /teams/{TEAM_ID}/files

Example Request

curl https://www.siasto.com/api/v2/files \ -u {YOUR_API_KEY}:

Example Response

{ "data": [ { "id": "doc_1a2b3c4d", "name": "TPS Report", "project_id": "prj_1a2b3c4d", "date_created": "2014-04-22T04:32:00+0000", }, ... ] }

CREATING A NEW FILE

POST /files POST /projects/{PROJECT_ID}/files

Include the following parameter:

name required

The name of the file. For example, TPS Report.

project_id string

The unique identifier of the project the file belongs to. For example, prj_1a2b3c4d.

Example Request

curl https://www.siasto.com/api/v2/files \ -u {YOUR_API_KEY}: \ -X POST \ -d "name=TPS Report" \ -d "project_id=prj_1a2b3c4d"

Example Response

{ "data": { "id": "doc_1a2b3c4d", "name": "TPS Report", "project_id": "prj_1a2b3c4d", "date_created": "2014-04-22T04:32:00+0000", } }

UPDATING A FILE

PUT /files/{FILE_ID}

There's only one attribute that can be changed:

name optional

The name of the file. For example, TPS Report.

Example Request

curl https://www.siasto.com/api/v2/files/{FILE_ID} \ -u {YOUR_API_KEY}: \ -X PUT \ -d "name=New File Name"

Example Response

{ "data": { "id": "doc_1a2b3c4d", "name": "New File Name", "project_id": "prj_1a2b3c4d", "date_created": "2014-04-22T04:32:00+0000", } }

DELETING A FILE

DELETE /files/{FILE_ID}

Example Request

curl https://www.siasto.com/api/v2/files/{FILE_ID} \ -u {YOUR_API_KEY}: \ -X DELETE

Example Response

{ "data": { "success": true, "message": "The file has been deleted." } }

COMMENTING ON A FILE

POST /files/{FILE_ID}/comments

Include the following parameter:

comment required

The text of the comment. For example, please use the new coversheets for this.

Example Request

curl https://www.siasto.com/api/v2/files/{FILE_ID}/comments \ -u {YOUR_API_KEY}: \ -X POST \ -d "comment=Please add a coversheet to this."

Example Response

{ "data": { "success": true, "message": "The comment has been posted." } }

EVENTS

THE EVENT OBJECT

Event objects appear on the calendar in Siasto.

id string

The unique identifier for the event. For example, evt_1a2b3c4d.

name string

The name of the event. For example, Weekly Meeting.

location string

The location of the event. For example, SF HQ, Room 42B.

invitee_ids array

An array of strings representing the IDs of users who've been invited to attend the event. For example, ["usr_1a2b3c4d", "usr_5e6f7g8h", ...].

start_date string

The date the event begins. For example, 2014-04-22.

start_time string or null

The time the event begins. For example, 04:32:00+0000. If null, it means the event lasts all day.

end_date string or null

The date the event begins. For example, 2014-04-22. If null, it means that no end date has been set.

end_time string or null

The time the event begins. For example, 05:32:00+0000. If null, it means the event lasts all day.

project_id string

The unique identifier of the project the event belongs to. For example, prj_1a2b3c4d.

date_created string

The date and time the event was created in ISO 8601 format. For example, 2014-04-22T04:32:00+0000.

RETRIEVING AN EVENT

GET /events/{EVENT_ID}

Example Request

curl https://www.siasto.com/api/v2/events/{EVENT_ID} \ -u {YOUR_API_KEY}:

Example Response

{ "data": { "id": "evt_1a2b3c4d", "name": "Weekly Meeting", "location": "SF HQ, Room 42B", "invitee_ids": ["usr_1a2b3c4d", "usr_5e6f7g8h"], "start_date": "2014-04-22", "start_time": "04:32:00+0000", "end_date": "2014-04-22", "end_time": "05:32:00+0000", "project_id": "prj_1a2b3c4d", "date_created": "2014-04-22T04:32:00+0000", } }

RETRIEVING MULTIPLE EVENTS

GET /events GET /teams/{EVENT_ID}/events GET /projects/{PROJECT_ID}/events

Example Request

curl https://www.siasto.com/api/v2/events \ -u {YOUR_API_KEY}:

Example Response

{ "data": [ { "id": "evt_1a2b3c4d", "name": "Weekly Meeting", "location": "SF HQ, Room 42B", "invitee_ids": ["usr_1a2b3c4d", "usr_5e6f7g8h"], "start_date": "2014-04-22", "start_time": "04:32:00+0000", "end_date": "2014-04-22", "end_time": "05:32:00+0000", "project_id": "prj_1a2b3c4d", "date_created": "2014-04-22T04:32:00+0000", }, ... ] }

CREATING A NEW EVENT

POST /events POST /projects/{PROJECT_ID}/events

Include the following parameter:

name required

The name of the event. For example, Weekly Meeting.

location optional

The location of the event. For example, SF HQ, Room 42B.

invitee_ids optional

An array of strings representing the IDs of users who've been invited to attend the event. For example, ["usr_1a2b3c4d", "usr_5e6f7g8h", ...].

start_date required

The date the event begins. For example, 2014-04-22.

start_time optional

The time the event begins. For example, 04:32:00+0000.

end_date optional

The date the event begins. For example, 2014-04-22. Required if the event has a start date.

end_time optional

The time the event begins. For example, 05:32:00+0000. Required if the event has a start time.

project_id required

The unique identifier of the project the event belongs to. For example, prj_1a2b3c4d.

Example Request

curl https://www.siasto.com/api/v2/events \ -u {YOUR_API_KEY}: \ -X POST \ -d "name=Weekly Meeting" \ -d "location=SF HQ, Room 42B" \ -d "invitee_ids[]=usr_1a2b3c4d" \ -d "invitee_ids[]=usr_5e6f7g8h" \ -d "start_date=2014-04-22" \ -d "start_time=04:32:00+0000" \ -d "project_id=prj_1a2b3c4d"

Example Response

{ "data": { "id": "evt_1a2b3c4d", "name": "Weekly Meeting", "location": "SF HQ, Room 42B", "invitee_ids": ["usr_1a2b3c4d", "usr_5e6f7g8h"], "start_date": "2014-04-22", "start_time": "04:32:00+0000", "end_date": null, "end_time": null, "project_id": "prj_1a2b3c4d", "date_created": "2014-04-22T04:32:00+0000", } }

UPDATING AN EVENT

PUT /events/{EVENT_ID}

Any of the following attributes can be updated:

name optional

The name of the event. For example, Weekly Meeting.

location optional

The location of the event. For example, SF HQ, Room 42B.

invitee_ids optional

An array of strings representing the IDs of users who've been invited to attend the event. For example, ["usr_1a2b3c4d", "usr_5e6f7g8h", ...].

start_date optional

The date the event begins. For example, 2014-04-22.

start_time optional

The time the event begins. For example, 04:32:00+0000.

end_date optional

The date the event begins. For example, 2014-04-22. Required if the event has a start date.

end_time optional

The time the event begins. For example, 05:32:00+0000. Required if the event has a start time.

Example Request

curl https://www.siasto.com/api/v2/events/{EVENT_ID} \ -u {YOUR_API_KEY}: \ -X PUT \ -d "name=New Event Name"

Example Response

{ "data": { "id": "evt_1a2b3c4d", "name": "New Event Name", "location": "SF HQ, Room 42B", "invitee_ids": ["usr_1a2b3c4d", "usr_5e6f7g8h"], "start_date": "2014-04-22", "start_time": "04:32:00+0000", "end_date": "2014-04-22", "end_time": "05:32:00+0000", "project_id": "prj_1a2b3c4d", "date_created": "2014-04-22T04:32:00+0000", } }

DELETING AN EVENT

DELETE /events/{EVENT_ID}

Example Requestt

curl https://www.siasto.com/api/v2/events/{EVENT_ID} \ -u {YOUR_API_KEY}: \ -X DELETE

Example Response

{ "data": { "success": true, "message": "The event has been deleted." } }

DISCUSSIONS

THE DISCUSSION OBJECT/h3>

Discussions are collections of comments made by different users within the team.

id string

The unique identifier for the discussion. For example, dsc_1a2b3c4d.

name string

The name of the discussion (comparable to the subject of an email). For example, Discussion about file XYZ.

subscriber_ids array

An array containing the IDs of the users who should be subscribed to the discussion. For example, [usr_1a2b3c4d, ...]. Subscribed users receive email updates when new comments are posted. Whether or not your specify your own ID, you will be subscribed to any discussion you create.

comments array

An array of the comments that make up the discussion. For example, [comment1, comment2, ...], where each comment is its own object:

comment string

The body of the comment. For example, Why yes, I'd love to see your baby pics..

user_id string or null

The unique identifier of the user who posted the comment. For example, usr_1a2b3c4d. Could be null if the comment's poster no longer exists.

date_created string

The date and time the comment was created in ISO 8601 format. For example, 2014-04-22T04:32:00+0000.

project_id string

The unique identifier of the file the discussion belongs to. For example, prj_1a2b3c4d.

task_id string or null

The unique identifier of the task the discussion belongs to. For example, tsk_1a2b3c4d. Will be null for discussions that are not attached to any task.

file_id string or null

The unique identifier of the file the discussion belongs to. For example, doc_1a2b3c4d. Will be null for discussions that are not attached to any file.

date_created string

The date and time the discussion was created in ISO 8601 format. For example, 2014-04-22T04:32:00+0000.

date_updated string

The date and time the discussion was last updated in ISO 8601 format. For example, 2014-04-22T04:32:00+0000. This generally refers to the date the most recent comment was made.

RETRIEVING A DISCUSSION

GET /discussions/{DISCUSSION_ID}

Example Request

curl https://www.siasto.com/api/v2/discussions/{DISC_ID} \ -u {YOUR_API_KEY}:

Example Response

{ "data": { "id": "dsc_1a2b3c4d", "name": "Discussion about task XYZ", "comments": [ { "comment": "This task is sooooo fun!", "user_id": "usr_1a2b3c4d", "date_created": "2014-04-22T04:32:00+0000" }, ... ], "subscriber_ids": ["usr_1a2b3c4d"], "project_id": "prj_1a2b3c4d", "task_id": "tsk_1a2b3c4d", "file_id": null, "date_created": "2014-04-22T04:32:00+0000", "date_updated": "2014-04-22T04:32:00+0000" } }

RETRIEVING MULTIPLE DISCUSSIONS

GET /discussions GET /teams/{TEAM_ID}/discussions GET /projects/{PROJECT_ID}/discussions

Example Request

curl https://www.siasto.com/api/v2/discussions \ -u {YOUR_API_KEY}:

Example Response

{ "data": [ { "id": "dsc_1a2b3c4d", "name": "Discussion about task XYZ", "comments": [ { "comment": "This task is sooooo fun!", "user_id": "usr_1a2b3c4d", "date_created": "2014-04-22T04:32:00+0000" }, ... ], "subscriber_ids": ["usr_1a2b3c4d"], "project_id": "prj_1a2b3c4d", "task_id": "tsk_1a2b3c4d", "file_id": null, "date_created": "2014-04-22T04:32:00+0000", "date_updated": "2014-04-22T04:32:00+0000" }, ... ] }

CREATING A NEW DISCUSSION

POST /discussions POST /projects/{PROJECT_ID}/discussions

Include the following parameter:

(Note that if you want to create a discussion attached to a particular task or file, use the methods for posting a comment toa task task/file directly.)

name required

The name of the discussion (comparable to the subject of an email). For example, Hey guys!.

comment required

The body of the first comment of the discussion. For example, How is everybody doing?.

project_id required

The unique identifier of the project the discussion belongs to. For example, prj_1a2b3c4d.

subscriber_ids optional

An array containing the IDs of the users who should be subscribed to the discussion. For example, [usr_1a2b3c4d, ...]. Subscribed users receive email updates when new comments are posted.

Example Request

curl https://www.siasto.com/api/v2/discussions \ -u {YOUR_API_KEY}: \ -X POST \ -d "name=Take a look" \ -d "comment=This is pretty cool: www.example.com"

Example Response

{ "data": { "id": "dsc_1a2b3c4d", "name": "Take a look", "comments": [ { "comment": "This is pretty cool: www.example.com", "user_id": "usr_1a2b3c4d", "date_created": "2014-04-22T04:32:00+0000" }, ... ], "subscriber_ids": ["usr_1a2b3c4d"], "project_id": "prj_1a2b3c4d", "task_id": null, "file_id": null, "date_created": "2014-04-22T04:32:00+0000", "date_updated": "2014-04-22T04:32:00+0000" } }

UPDATING A DISCUSSION

PUT /discussions/{DISCUSSION_ID}

There's only one attribute that can be changed:

name optional

The name of the discussion (comparable to the subject of an email). For example, Hey guys!.

Example Request

curl https://www.siasto.com/api/v2/discussions/{DISC_ID} \ -u {YOUR_API_KEY}: \ -X PUT \ -d "name=New Discussion Name"

Example Response

{ "data": { "id": "dsc_1a2b3c4d", "name": "New Discussion Name", "comments": [ { "comment": "This is pretty cool: www.example.com", "user_id": "usr_1a2b3c4d", "date_created": "2014-04-22T04:32:00+0000" }, ... ], "subscriber_ids": ["usr_1a2b3c4d"], "project_id": "prj_1a2b3c4d", "task_id": null, "file_id": null, "date_created": "2014-04-22T04:32:00+0000", "date_updated": "2014-04-22T04:32:00+0000" } }

DELETING A DISCUSSION

DELETE /discussions/{DISCUSSION_ID}

Example Request

curl https://www.siasto.com/api/v2/discussions/{DISC_ID} \ -u {YOUR_API_KEY}: \ -X DELETE

Example Response

{ "data": { "success": true, "message": "The discussion has been deleted." } }

COMMENTING ON A DISCUSSION

POST /discussions/{DISCUSSION_ID}/comments

Include the following parameter:

comment required

The text of the comment. For example, please use the new coversheets for this.

Example Request

curl https://www.siasto.com/api/v2/discussions/{DISC_ID}/comments \ -u {YOUR_API_KEY}: \ -X POST \ -d "comment=Please add a coversheet to this."

Example Response

{ "data": { "success": true, "message": "The comment has been posted." } }