Events

Events are appointments, happenings etc. that take place on a certain time in a certain place.

Events can be posted in Chain calendar (restricted by unit and user types), Unit calendar (restricted by user types) and My Calendar (only the user him- or herself)

TIP

Recurring events are still not implemented in the API. They will be... soon.

Get Events

curl "https://example.ziik.io/api/events"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"
{
  "hits": [
    {
        "id": 1202,
        "content_type": "event",
        "permissions": {
            "edit": true,
            "delete": true
        },
        "title": "Test event private",
        "dates": [{
            "start": 1465632000,
            "end": 1465658100
        }],
        "all_day": false,
        "date": null,
        "location": "test location",
        "link": "https://example.com",
        "type": "user",
        "files": [],
        "body": "blah blah blah blah",
        "userTypes": [],
        "units": [],
        "shared": false,
        "url": "api/events/1202"
    },
    {
        "id": 1010,
        "content_type": "event",
        "permissions": {
            "edit": true,
            "delete": true
        },
        "title": "Unit event",
        "dates": [{
            "start": 1463724000,
            "end": 1463727600
        }],
        "all_day": false,
        "date": null,
        "location": null,
        "link": "https://example.com",
        "type": "unit",
        "files": [],
        "body": "This event is in the user's unit",
        "userTypes": [
          {
              "id": 345,
              "name": "Example User Type",
              "url": "api/usertypes/345"
          },
          {
              "id": 456,
              "name": "Other User Type",
              "url": "api/usertypes/456"
          }
        ],
        "units": [
          {
              "content_type": "unit",
              "id": 567,
              "name": "Example unit",
              "url": "api/units/567"
          }
        ],
        "shared": false,
        "url": "api/events/1010"
    },
    {
        "id": 1111,
        "content_type": "event",
        "permissions": {
            "edit": true,
            "delete": true
        },
        "title": "All day event",
        "dates": [],
        "all_day": true,
        "date": "2018-11-01",
        "location": null,
        "link": "https://example.com",
        "type": "unit",
        "files": [],
        "body": "This event is in the user's unit",
        "userTypes": [
          {
              "id": 345,
              "name": "Example User Type",
              "url": "api/usertypes/345"
          },
          {
              "id": 456,
              "name": "Other User Type",
              "url": "api/usertypes/456"
          }
        ],
        "units": [
          {
              "content_type": "unit",
              "id": 567,
              "name": "Example unit",
              "url": "api/units/567"
          }
        ],
        "shared": false,
        "url": "api/events/1010"
    }
  ],
    "meta": {
        "pagination": {
            "total": 315,
            "count": 50,
            "per_page": 50,
            "current_page": 2,
            "total_pages": 7,
            "links": []
        }
    }
}

This endpoint retrieves a list of events.

HTTP Request

GET https://example.ziik.io/api/events

Query Parameters

ParameterTypeDefaultDescription
typeStringNULLIf set, only show events with this type - can be 'chain', 'unit' or 'user'
pageInteger1Page number for pagination.
limitInteger50Number of records to return per page.
startIntegerNULLUnix Timestamp of earliest event start
endIntegerNULLUnix Timestamp of latest event start

Get Single Event

curl "https://example.ziik.io/api/events/1203"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"

The above command returns JSON structured like this:

  {
      "id": 1204,
      "content_type": "event",
      "permissions": {
          "edit": true,
          "delete": true
      },
      "title": "Some event",
      "dates": [{
          "start": 1466064000,
          "end": 1466086500
      }],
      "all_day": false,
      "date": null,
      "location": "Meeting Room #2",
      "link": "https://example.com",
      "type": "chain",
      "files": [],
      "body": "This is an event event",
      "userTypes": [
        {
            "id": 345,
            "name": "Example User Type",
            "url": "api/usertypes/345"
        },
        {
            "id": 456,
            "name": "Other User Type",
            "url": "api/usertypes/456"
        }
      ],
      "units": [
        {
            "content_type": "unit",
            "id": 567,
            "name": "Example unit",
            "url": "api/units/567"
        }
      ],
      "shared": false,
      "url": "api/events/1204"
  }

This endpoint returns a single event

HTTP Request

GET https://example.ziik.io/api/events/ID

URL Parameters

ParameterTypeDescription
IDIntegerThe ID of the event

Permissions Required

  • User's user type in event's user types
  • AND Event type is not user and User's unit within the event's units
  • OR Event type is user and belongs to the user

Create Event

curl -i -X POST "https://example.ziik.io/api/events"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"
  -d "{ [...] }"

The above command returns 201 Created with a location header for where to find the newly created event

HTTP/1.0 201 Created
Location: https://example.ziik.io/api/events/1234
{
    "message": "Event created"
}

This endpoint creates a new event.

Setting an event as recurrent can be a complex task. See this page for more info: https://www.textmagic.com/free-tools/rrule-generator.

HTTP Request

POST https://example.ziik.io/api/events

Request Parameters

ParameterTypeRequiredDescription
titleStringYesTitle for the event.
bodyStringNoDescription for the event.
typeStringYes'chain', 'user'
locationStringNoFreetext describing the location of the event
linkStringNoFull URL including protocol - e.g. https://example.com
startIntegerYesUnix Timestamp of event start time
endIntegerYesUnix Timestamp of event end time
all_dayIntegerNo1 = true, 0 = false. When set to "1", date must also be provided and start + end are ignored
dateDateIf all_day = 1A date in the format "YYYY-MM-DD"
recurrenceArrayNoAn array of recurrence rules, in RRULE format.
- freqStringYesValid values are: daily, weekly, monthly, yearly.
- untilDateNoRepeat event until this date in the format "YYYY-MM-DD".
- countIntegerNoRepeat X times.
- intervalIntegerNoRepeat every X day/week/month/year.
- bydayString or ArrayNoBy day. One or more of values: MO,TU,WE,TH,FR,SA,SU. For weekdays use MO+TU+WE+TH+FR. For weekends use SA+SU.
- bymonthdayStringNoBy day of the month. Values: 1-31.
- bymonthStringNoBy month. Values: 1-12
- bysetposStringNoBy the X of Y of month. Values: 1-5. Used in conjunction with "byday". For last day use -1.
unitsArrayNoUnits this event should be published in - applicable for non-'user' type events only
userTypesArrayNoUser type IDs of the user types, who can read this - applicable for 'chain' events
fileCountIntegerNoNumber of files that will be uploaded (type 'upload') in total, including subsequent POSTs to /api/events/ID/files
filesArrayNoFile data for files to accompany the event. If provided, must be an array of arrays with the following values
- typeStringYesType of file - can be either 'upload', 'youtube' or 'vimeo'.
- nameStringYesFile name.
- dataStringYesIf type is 'upload' this must be the base64 encoded content of the file. Else it must be the Youtube/Vimeo embed URL.
sharesArrayNoUser IDs of users this event is shared with

Permissions Required

  • Write permission to events for the chosen event type

Edit Event

curl -i -X PATCH "https://example.ziik.io/api/events/123"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"
  -d "{ [...] }"

The above command returns 204 No Content on successful update.

HTTP/1.0 204 No Content

This endpoint updates an existing event.

HTTP Request

PATCH https://example.ziik.io/api/events/ID

Request Parameters

ParameterTypeRequiredDescription
titleStringNoTitle for the event.
bodyStringNoDescription for the event.
typeStringNo'chain', 'user'
locationStringNoFreetext describing the location of the event
linkStringNoFull URL including protocol - e.g. https://example.com
startIntegerNoUnix Timestamp of event start time
endIntegerNoUnix Timestamp of event end time
all_dayIntegerNo1 = true, 0 = false. When set to "1", date must also be provided and start + end are ignored
dateDateIf all_day = 1A date in the format "YYYY-MM-DD"
recurrenceArrayNoAn array of recurrence rules, in RRULE format.
- freqStringYesValid values are: daily, weekly, monthly, yearly.
- untilDateNoRepeat event until this date in the format "YYYY-MM-DD".
- countIntegerNoRepeat X times.
- intervalIntegerNoRepeat every X day/week/month/year.
- bydayString or ArrayNoBy day. One or more of values: MO,TU,WE,TH,FR,SA,SU. For weekdays use MO+TU+WE+TH+FR. For weekends use SA+SU.
- bymonthdayStringNoBy day of the month. Values: 1-31.
- bymonthStringNoBy month. Values: 1-12
- bysetposStringNoBy the X of Y of month. Values: 1-5. Used in conjunction with "byday". For last day use -1.
unitsArrayNoUnits this event should be published in - applicable for 'chain' type events only
filesArrayNoFile data for files to accompany the event. If provided, existing files are cleared. Must be an array of arrays with the following values
- typeStringYesType of file - can be either 'upload', 'youtube' or 'vimeo'.
- nameStringYesFile name.
- dataStringYesIf type is 'upload' this must be the base64 encoded content of the file. Else it must be the Youtube/Vimeo embed URL.
sharesArrayNoUser IDs of users this event is shared with

Permissions Required

  • Administer permission to events for the chosen event type

Delete Event

curl -i -X DELETE "https://example.ziik.io/api/events/123"
  -H "Authorization: Bearer aaaaaa.bbbbbbb.ccccccc"

The above command returns a 204 No Content header on success:

HTTP/1.0 204 No Content

This endpoint deletes an event.

HTTP Request

DELETE https://example.ziik.io/api/events/ID

URL Parameters

ParameterTypeDescription
IDIntegerThe ID of the event to delete

Permissions Required

  • Administer permission to events for the chosen event type

Mark Event Seen

curl -i -X POST "https://example.ziik.io/api/events/123/seen"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"
  -d "{ [...] }"

The above command returns 204 No Content on success

HTTP/1.0 204 No Content

This endpoint marks an event as seen for the current user.

HTTP Request

POST https://example.ziik.io/api/events/123/seen

Request Parameters

None

Permissions Required

  • Read access to the event (See "Get Single Event")

Get Upcoming Events

curl "https://example.ziik.io/api/events"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"
{
  "hits": [
    {
        "id": 1202,
        "content_type": "event",
        "permissions": {
            "edit": true,
            "delete": true
        },
        "title": "Test event private",
        "dates": [{
            "start": 1465632000,
            "end": 1465658100
        }],
        "all_day": false,
        "date": null,
        "location": "test location",
        "link": "https://example.com",
        "type": "user",
        "files": [],
        "body": "blah blah blah blah",
        "userTypes": [],
        "units": [],
        "url": "api/events/1202"
    },
    {
        "id": 1010,
        "content_type": "event",
        "permissions": {
            "edit": true,
            "delete": true
        },
        "title": "Unit event",
        "dates": [{
            "start": 1463724000,
            "end": 1463727600
        }],
        "all_day": false,
        "date": null,
        "location": null,
        "link": "https://example.com",
        "type": "unit",
        "files": [],
        "body": "This event is in the user's unit",
        "userTypes": [
          {
              "id": 345,
              "name": "Example User Type",
              "url": "api/usertypes/345"
          },
          {
              "id": 456,
              "name": "Other User Type",
              "url": "api/usertypes/456"
          }
        ],
        "units": [
          {
              "content_type": "unit",
              "id": 567,
              "name": "Example unit",
              "url": "api/units/567"
          }
        ],
        "url": "api/events/1010"
    }
  ],
    "meta": {
        "pagination": {
            "total": 315,
            "count": 50,
            "per_page": 50,
            "current_page": 2,
            "total_pages": 7,
            "links": []
        }
    }
}

This endpoint retrieves the next 3 event occurrences. If an event has multiple dates, it can appear multiple times in the list

HTTP Request

GET https://example.ziik.io/api/events/upcoming

Query Parameters

  • None

Mark Event Seen

curl -i -X POST "https://example.ziik.io/api/events/123/seen"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"
  -d "{ [...] }"

The above command returns 204 No Content on success

HTTP/1.0 204 No Content

This endpoint marks an event as seen for the current user.

HTTP Request

POST https://example.ziik.io/api/events/123/seen

Request Parameters

None

Permissions Required

  • Read access to the event

Add Files To Event

curl -i -X POST "https://example.ziik.io/api/events/files"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"
  -d "{ [...] }"

The above command returns 204 No Content on success

HTTP/1.0 204 No Content

This endpoint adds files to an existing event.

HTTP Request

POST https://example.ziik.io/api/events/files

Request Parameters

ParameterTypeDescription
idIntegerThe ID of the event to add files to
filesArrayNo
- typeStringYes
- nameStringYes
- dataStringYes

Permissions Required

  • Event edit access

Delete File From Event

curl -i -X DELETE "https://example.ziik.io/api/events/124/files/12345"
  -H "Authorization: Bearer aaaaaa.bbbbbbb.ccccccc"

The above command returns a 204 No Content header on success:

HTTP/1.0 204 No Content

This endpoint deletes a file from an event.

HTTP Request

DELETE https://example.ziik.io/api/events/<EventID>/files/<FileID>

URL Parameters

ParameterTypeDescription
EventIDIntegerThe ID of the event
FileIDIntegerThe ID of the file to delete

Permissions Required

  • Event edit access