Quick Reference

Use this page to explore the APIs or bookmark it to quickly jump to a specific endpoint while developing your app. All APIs require https / TLS. You'll also notice the v1 in each endpoint URL. This indicates that the latest API is currently version 1.0. If we ever have to break backwards compatibility the version number will be bumped.

People

People are registered users of the Spark application. Searching and viewing People requires an auth token with a scope of spark:people_read. Viewing the list of all People in your Organization requires an administrator auth token with spark-admin:people_read scope. Adding, updating, and removing People requires an administrator auth token with the spark-admin:people_write scope.

To learn more about managing people in a room see the Memberships API

Method  
get https://api.ciscospark.com/v1/people
post https://api.ciscospark.com/v1/people
get https://api.ciscospark.com/v1/people/{personId}
put https://api.ciscospark.com/v1/people/{personId}
delete https://api.ciscospark.com/v1/people/{personId}
get https://api.ciscospark.com/v1/people/me

Rooms

Rooms are virtual meeting places where people post messages and collaborate to get work done. This API is used to manage the rooms themselves. Rooms are created and deleted with this API. You can also update a room to change its title, for example.

To create a team room, specify the a teamId in POST payload. Note that once a room is added to a team, it cannot be moved. To learn more about managing teams, see the Teams API.

To manage people in a room see the Memberships API.

To post content see the Messages API.

Method  
get https://api.ciscospark.com/v1/rooms
post https://api.ciscospark.com/v1/rooms
get https://api.ciscospark.com/v1/rooms/{roomId}
put https://api.ciscospark.com/v1/rooms/{roomId}
delete https://api.ciscospark.com/v1/rooms/{roomId}

Memberships

Memberships represent a person's relationship to a room. Use this API to list members of any room that you're in or create memberships to invite someone to a room. Memberships can also be updated to make someome a moderator or deleted to remove them from the room.

Just like in the Spark app, you must be a member of the room in order to list its memberships or invite people.

Method  
get https://api.ciscospark.com/v1/memberships
post https://api.ciscospark.com/v1/memberships
get https://api.ciscospark.com/v1/memberships/{membershipId}
put https://api.ciscospark.com/v1/memberships/{membershipId}
delete https://api.ciscospark.com/v1/memberships/{membershipId}

Messages

Messages are how we communicate in a room. In Spark, each message is displayed on its own line along with a timestamp and sender information. Use this API to list, create, and delete messages.

Message can contain plain text, rich text, and a file attachment.

Just like in the Spark app, you must be a member of the room in order to target it with this API.

Method  
get https://api.ciscospark.com/v1/messages
post https://api.ciscospark.com/v1/messages
get https://api.ciscospark.com/v1/messages/{messageId}
delete https://api.ciscospark.com/v1/messages/{messageId}

Teams

Teams are groups of people with a set of rooms that are visible to all members of that team. This API is used to manage the teams themselves. Teams are created and deleted with this API. You can also update a team to change its name, for example.

To manage people in a team see the Team Memberships API.

To manage team rooms see the Rooms API.

Method  
get https://api.ciscospark.com/v1/teams
post https://api.ciscospark.com/v1/teams
get https://api.ciscospark.com/v1/teams/{teamId}
put https://api.ciscospark.com/v1/teams/{teamId}
delete https://api.ciscospark.com/v1/teams/{teamId}

Team Memberships

Team Memberships represent a person's relationship to a team. Use this API to list members of any team that you're in or create memberships to invite someone to a team. Team memberships can also be updated to make someone a moderator or deleted to remove them from the team.

Just like in the Spark app, you must be a member of the team in order to list its memberships or invite people.

Method  
get https://api.ciscospark.com/v1/team/memberships
post https://api.ciscospark.com/v1/team/memberships
get https://api.ciscospark.com/v1/team/memberships/{membershipId}
put https://api.ciscospark.com/v1/team/memberships/{membershipId}
delete https://api.ciscospark.com/v1/team/memberships/{membershipId}

Webhooks

Webhooks allow your app to be notified via HTTP when a specific event occurs on Spark. For example, your app can register a webhook to be notified when a new message is posted into a specific room.

Events trigger in near real-time allowing your app and backend IT systems to stay in sync with new content and room activity.

Check the Webhooks Guide and our blog regularly for announcements of additional webhook resources and event types.

Method  
get https://api.ciscospark.com/v1/webhooks
post https://api.ciscospark.com/v1/webhooks
get https://api.ciscospark.com/v1/webhooks/{webhookId}
put https://api.ciscospark.com/v1/webhooks/{webhookId}
delete https://api.ciscospark.com/v1/webhooks/{webhookId}

Organizations

A set of people in Cisco Spark. Organizations may manage other organizations or be managed themselves. This organizations resource can be accessed only by an admin.

Method  
get https://api.ciscospark.com/v1/organizations
get https://api.ciscospark.com/v1/organizations/{orgId}

Licenses

An allowance for features and services that are provided to users on a Cisco Spark services subscription. Cisco and its partners manage the amount of licenses provided to administrators and users. This license resource can be accessed only by an admin.

Method  
get https://api.ciscospark.com/v1/licenses
get https://api.ciscospark.com/v1/licenses/{licenseId}

Roles

A persona for an authenticated user, corresponding to a set of privileges within an organization. This roles resource can be accessed only by an admin.

Method  
get https://api.ciscospark.com/v1/roles
get https://api.ciscospark.com/v1/roles/{roleId}

Events

The resource endpoints such as /rooms, /messages, /memberships, etc. represent the current state of data in Spark. The /events resource represents the log of state changes which led to the current state of these resources; it details when a resource changed and who made the change.

For example, when a user posts a message in a room, this will result in a new message, available via the /messages resource. It will also result in a new event, available on the /events resource. If the user then deletes their message, this will result in the message no longer being returned on the /messages resource but it will result in a new event for the message deletion on the /events resource.

Events are available for the following resources when they are created, updated, or deleted:

  • messages
  • memberships

Method  
get https://api.ciscospark.com/v1/events
get https://api.ciscospark.com/v1/events/{eventId}

Policies

Policies give organization administrators more control over the Integrations available for use within their organization. By default, any user can add an integration for use with Spark. To restrict the usage of integrations within an organization, create policies to define what is either allowed or disallowed by the organization.

Each policy contains an explicit action to either allow or deny access to external integrations. Policy options can specify which integrations, people, and/or authorization scopes it will apply to. These options may be combined to create very specific policies or omitted to cover a broader range of integrations.

Listing and viewing policies requires an administrator auth token with a scope of spark-admin:policies_read. Adding, updating, and removing policies requires an administrator auth token with the spark-admin:policies_write scope. To find out more about authorization scopes, see the scopes documentation.

Policy Options

  • Application — All integrations have a unique identifier, their appId. To determine the appId for a particular integration, please contact the developer of the integration.
  • People — Each person has a unique identifier, their personId. This ID can be found via the People API.
  • Scopes — Each integration is assigned one or more scopes, which define what it can do and what information within Spark it has access to. Policies can allow or disallow integrations by which particular scope or scopes they require. For a list of scopes integrations can use, please see the scopes documentation.
  • Name — The policy name is a free-form text field to help you describe each policy.

Policy Evaluation

Policies are evaluated from most to least specific, with an implicit allow if none apply. When no policies are present for an organization, all integrations are allowed.

When multiple policies match, the one with the latest (most recent) creation date will apply.

Examples

Limit Access to Certain People

To limit an integration to certain people, grant access to the permitted users and deny access to everyone else.

  1. Grant access to the integration to specific users:

    {
      "appId": "Y2lzY29zcGFyazovL3VzL1JPT00vYmJjZWIxYWQtNDNmMS0zYjU4LTkxNDctZjE0YmIwYzRkMTU0",
      "name": "Allow Integration 123",
      "personIds": [
        "Y2lzY29zcGFyazovL3VzL1JPT00vYmJjZWIxYWQtNDNmMS0zYjU4LTkxNDctZjE0YmIwYzRkMTU0",
        "Y2lzY29zcGFyazovL3VzL1JPT00vYmJjZWIxYWQtNDNmMS0zYjU4LTkxNDctZjE0YmIwYzRkMTU0",
        "Y2lzY29zcGFyazovL3VzL0NBTExTLzU0MUFFMzBFLUUyQzUtNERENi04NTM4LTgzOTRDODYzM0I3MQo"
      ],
      "scopes": [],
      "action": "allow"
    }
    
  2. Deny access to everyone else:

    {
      "appId": "Y2lzY29zcGFyazovL3VzL1JPT00vYmJjZWIxYWQtNDNmMS0zYjU4LTkxNDctZjE0YmIwYzRkMTU0",
      "name": "Deny Integration 123",
      "personIds": [],
      "scopes": [],
      "action": "deny"
    }
    

Grant Everyone Access to a Single Integration

To allow one integration and deny all others, create two policies, one to allow the specific integration (identified by the appId) and another policy to deny all other integrations (by omitting an appId). Because the second policy does not specify an appId, personId, or scope, it will act as a wildcard entry which will match all integrations.

  1. Grant access to the integration:

    {
      "appId": "Y2lzY29zcGFyazovL3VzL1JPT00vYmJjZWIxYWQtNDNmMS0zYjU4LTkxNDctZjE0YmIwYzRkMTU0",
      "name": "Allow Integration 123",
      "personIds": [],
      "scopes": [],
      "action": "allow"
    }
    
  2. Deny access to all integrations:

    {
      "appId": "",
      "name": "Deny All",
      "personIds": [],
      "scopes": [],
      "action": "deny"
    }
    

Method  
get https://api.ciscospark.com/v1/policies
post https://api.ciscospark.com/v1/policies
get https://api.ciscospark.com/v1/policies/{policyId}
put https://api.ciscospark.com/v1/policies/{policyId}
delete https://api.ciscospark.com/v1/policies/{policyId}