User API Doc¶

CiscoSparkAPI¶

The CiscoSparkAPI class is the main interface for the package. All of the Spark APIs (people, rooms, etc.) and their API endpoints have been wrapped and hierarchically organized underneath the CiscoSparkAPI class.

class ciscosparkapi.CiscoSparkAPI[source]¶

Cisco Spark API wrapper.

Creates a ‘session’ for all API calls through a created CiscoSparkAPI object. The ‘session’ handles authentication, provides the needed headers, and checks all responses for error conditions.

CiscoSparkAPI wraps all of the individual Cisco Spark APIs and represents them in a simple hierarchical structure.

CiscoSparkAPI:

people

rooms

memberships

messages

teams

team_memberships

webhooks

organizations

licenses

roles

events

access_tokens

__init__(access_token=None, base_url='https://api.ciscospark.com/v1/', timeout=None, single_request_timeout=60, wait_on_rate_limit=True, object_factory=<function spark_data_factory>)[source]¶

Create a new CiscoSparkAPI object.

An access token must be used when interacting with the Cisco Spark API. This package supports two methods for you to provide that access token:

You may manually specify the access token via the access_token argument, when creating a new CiscoSparkAPI object.

If an access_token argument is not supplied, the package checks for a SPARK_ACCESS_TOKEN environment variable.

A ciscosparkapiException is raised if an access token is not provided via one of these two methods.

Parameters:	access_token (basestring) – The access token to be used for API calls to the Cisco Spark service. Defaults to checking for a SPARK_ACCESS_TOKEN environment variable. base_url (basestring) – The base URL to be prefixed to the individual API endpoint suffixes. Defaults to ciscosparkapi.DEFAULT_BASE_URL. timeout (int) – [deprecated] Timeout (in seconds) for RESTful HTTP requests. Defaults to ciscosparkapi.DEFAULT_TIMEOUT. single_request_timeout (int) – Timeout (in seconds) for RESTful HTTP requests. Defaults to ciscosparkapi.DEFAULT_SINGLE_REQUEST_TIMEOUT. wait_on_rate_limit (bool) – Enables or disables automatic rate-limit handling. Defaults to ciscosparkapi.DEFAULT_WAIT_ON_RATE_LIMIT. object_factory (callable) – The factory function to use to create Python objects from the returned Cisco Spark JSON data objects.
Returns:	A new CiscoSparkAPI object.
Return type:	CiscoSparkAPI
Raises:	`TypeError` – If the parameter types are incorrect. `ciscosparkapiException` – If an access token is not provided via the access_token argument or SPARK_ACCESS_TOKEN environment variable.

single_request_timeout¶: Timeout (in seconds) for an single HTTP request.

wait_on_rate_limit¶: Automatic rate-limit handling enabled / disabled.

people¶

class ciscosparkapi.api.people.PeopleAPI[source]¶

Cisco Spark People API.

Wraps the Cisco Spark People API and exposes the API as native Python methods that return native Python objects.

list(email=None, displayName=None, id=None, orgId=None, max=None, **request_parameters)[source]¶

List people

This method supports Cisco Spark’s implementation of RFC5988 Web Linking to provide pagination support. It returns a generator container that incrementally yields all people returned by the query. The generator will automatically request additional ‘pages’ of responses from Spark as needed until all responses have been returned. The container makes the generator safe for reuse. A new API call will be made, using the same parameters that were specified when the generator was created, every time a new iterator is requested from the container.

Parameters:	email (basestring) – The e-mail address of the person to be found. displayName (basestring) – The complete or beginning portion of the displayName to be searched. id (basestring) – List people by ID. Accepts up to 85 person IDs separated by commas. orgId (basestring) – The organization ID. max (int) – Limit the maximum number of items returned from the Spark service per request. **request_parameters – Additional request parameters (provides support for parameters that may be added in the future).
Returns:	A GeneratorContainer which, when iterated, yields the people returned by the Cisco Spark query.
Return type:	GeneratorContainer
Raises:	`TypeError` – If the parameter types are incorrect. `SparkApiError` – If the Cisco Spark cloud returns an error.

create(emails, displayName=None, firstName=None, lastName=None, avatar=None, orgId=None, roles=None, licenses=None, **request_parameters)[source]¶

Create a new user account for a given organization

Only an admin can create a new user account.

Parameters:	emails (list) – Email address(es) of the person (list of strings). displayName (basestring) – Full name of the person. firstName (basestring) – First name of the person. lastName (basestring) – Last name of the person. avatar (basestring) – URL to the person’s avatar in PNG format. orgId (basestring) – ID of the organization to which this person belongs. roles (list) – Roles of the person (list of strings containing the role IDs to be assigned to the person). licenses (list) – Licenses allocated to the person (list of strings - containing the license IDs to be allocated to the person). **request_parameters – Additional request parameters (provides support for parameters that may be added in the future).
Returns:	A Person object with the details of the created person.
Return type:	Person
Raises:	`TypeError` – If the parameter types are incorrect. `SparkApiError` – If the Cisco Spark cloud returns an error.

get(personId)[source]¶

Get a person’s details, by ID.

Parameters:	personId (basestring) – The ID of the person to be retrieved.
Returns:	A Person object with the details of the requested person.
Return type:	Person
Raises:	`TypeError` – If the parameter types are incorrect. `SparkApiError` – If the Cisco Spark cloud returns an error.

update(personId, emails=None, displayName=None, firstName=None, lastName=None, avatar=None, orgId=None, roles=None, licenses=None, **request_parameters)[source]¶

Update details for a person, by ID.

Only an admin can update a person’s details.

Email addresses for a person cannot be changed via the Spark API.

Include all details for the person. This action expects all user details to be present in the request. A common approach is to first GET the person’s details, make changes, then PUT both the changed and unchanged values.

Parameters:	personId (basestring) – The person ID. emails (list) – Email address(es) of the person (list of strings). displayName (basestring) – Full name of the person. firstName (basestring) – First name of the person. lastName (basestring) – Last name of the person. avatar (basestring) – URL to the person’s avatar in PNG format. orgId (basestring) – ID of the organization to which this person belongs. roles (list) – Roles of the person (list of strings containing the role IDs to be assigned to the person). licenses (list) – Licenses allocated to the person (list of strings - containing the license IDs to be allocated to the person). **request_parameters – Additional request parameters (provides support for parameters that may be added in the future).
Returns:	A Person object with the updated details.
Return type:	Person
Raises:	`TypeError` – If the parameter types are incorrect. `SparkApiError` – If the Cisco Spark cloud returns an error.

delete(personId)[source]¶

Remove a person from the system.

Only an admin can remove a person.

Parameters:	personId (basestring) – The ID of the person to be deleted.
Raises:	`TypeError` – If the parameter types are incorrect. `SparkApiError` – If the Cisco Spark cloud returns an error.

me()[source]¶

Get the details of the person accessing the API.

Raises:	`SparkApiError` – If the Cisco Spark cloud returns an error.

rooms¶

class ciscosparkapi.api.rooms.RoomsAPI[source]¶

Cisco Spark Rooms API.

Wraps the Cisco Spark Rooms API and exposes the API as native Python methods that return native Python objects.

list(teamId=None, type=None, sortBy=None, max=None, **request_parameters)[source]¶

List rooms.

By default, lists rooms to which the authenticated user belongs.

This method supports Cisco Spark’s implementation of RFC5988 Web Linking to provide pagination support. It returns a generator container that incrementally yields all rooms returned by the query. The generator will automatically request additional ‘pages’ of responses from Spark as needed until all responses have been returned. The container makes the generator safe for reuse. A new API call will be made, using the same parameters that were specified when the generator was created, every time a new iterator is requested from the container.

Parameters:	teamId (basestring) – Limit the rooms to those associated with a team, by ID. type (basestring) – ‘direct’ returns all 1-to-1 rooms. group returns all group rooms. If not specified or values not matched, will return all room types. sortBy (basestring) – Sort results by room ID (id), most recent activity (lastactivity), or most recently created (created). max (int) – Limit the maximum number of items returned from the Spark service per request. **request_parameters – Additional request parameters (provides support for parameters that may be added in the future).
Returns:	A GeneratorContainer which, when iterated, yields the rooms returned by the Cisco Spark query.
Return type:	GeneratorContainer
Raises:	`TypeError` – If the parameter types are incorrect. `SparkApiError` – If the Cisco Spark cloud returns an error.

create(title, teamId=None, **request_parameters)[source]¶

Create a room.

The authenticated user is automatically added as a member of the room.

Parameters:	title (basestring) – A user-friendly name for the room. teamId (basestring) – The team ID with which this room is associated. **request_parameters – Additional request parameters (provides support for parameters that may be added in the future).
Returns:	A Room with the details of the created room.
Return type:	Room
Raises:	`TypeError` – If the parameter types are incorrect. `SparkApiError` – If the Cisco Spark cloud returns an error.

get(roomId)[source]¶

Get the details of a room, by ID.

Parameters:	roomId (basestring) – The ID of the room to be retrieved.
Returns:	A Room object with the details of the requested room.
Return type:	Room
Raises:	`TypeError` – If the parameter types are incorrect. `SparkApiError` – If the Cisco Spark cloud returns an error.

update(roomId, title=None, **request_parameters)[source]¶

Update details for a room, by ID.

Parameters:	roomId (basestring) – The room ID. title (basestring) – A user-friendly name for the room. **request_parameters – Additional request parameters (provides support for parameters that may be added in the future).
Returns:	A Room object with the updated Spark room details.
Return type:	Room
Raises:	`TypeError` – If the parameter types are incorrect. `SparkApiError` – If the Cisco Spark cloud returns an error.

delete(roomId)[source]¶

Delete a room.

Parameters:	roomId (basestring) – The ID of the room to be deleted.
Raises:	`TypeError` – If the parameter types are incorrect. `SparkApiError` – If the Cisco Spark cloud returns an error.

memberships¶

class ciscosparkapi.api.memberships.MembershipsAPI[source]¶

Cisco Spark Memberships API.

Wraps the Cisco Spark Memberships API and exposes the API as native Python methods that return native Python objects.

list(roomId=None, personId=None, personEmail=None, max=None, **request_parameters)[source]¶

List room memberships.

By default, lists memberships for rooms to which the authenticated user belongs.

Use query parameters to filter the response.

Use roomId to list memberships for a room, by ID.

Use either personId or personEmail to filter the results.

This method supports Cisco Spark’s implementation of RFC5988 Web Linking to provide pagination support. It returns a generator container that incrementally yields all memberships returned by the query. The generator will automatically request additional ‘pages’ of responses from Spark as needed until all responses have been returned. The container makes the generator safe for reuse. A new API call will be made, using the same parameters that were specified when the generator was created, every time a new iterator is requested from the container.

Parameters:	roomId (basestring) – Limit results to a specific room, by ID. personId (basestring) – Limit results to a specific person, by ID. personEmail (basestring) – Limit results to a specific person, by email address. max (int) – Limit the maximum number of items returned from the Spark service per request. **request_parameters – Additional request parameters (provides support for parameters that may be added in the future).
Returns:	A GeneratorContainer which, when iterated, yields the memberships returned by the Cisco Spark query.
Return type:	GeneratorContainer
Raises:	`TypeError` – If the parameter types are incorrect. `SparkApiError` – If the Cisco Spark cloud returns an error.

create(roomId, personId=None, personEmail=None, isModerator=False, **request_parameters)[source]¶

Add someone to a room by Person ID or email address.

Add someone to a room by Person ID or email address; optionally making them a moderator.

Parameters:	roomId (basestring) – The room ID. personId (basestring) – The ID of the person. personEmail (basestring) – The email address of the person. isModerator (bool) – Set to True to make the person a room moderator. **request_parameters – Additional request parameters (provides support for parameters that may be added in the future).
Returns:	A Membership object with the details of the created membership.
Return type:	Membership
Raises:	`TypeError` – If the parameter types are incorrect. `SparkApiError` – If the Cisco Spark cloud returns an error.

get(membershipId)[source]¶

Get details for a membership, by ID.

Parameters:	membershipId (basestring) – The membership ID.
Returns:	A Membership object with the details of the requested membership.
Return type:	Membership
Raises:	`TypeError` – If the parameter types are incorrect. `SparkApiError` – If the Cisco Spark cloud returns an error.

update(membershipId, isModerator=None, **request_parameters)[source]¶

Update properties for a membership, by ID.

Parameters:	membershipId (basestring) – The membership ID. isModerator (bool) – Set to True to make the person a room moderator. **request_parameters – Additional request parameters (provides support for parameters that may be added in the future).
Returns:	A Membership object with the updated Spark membership details.
Return type:	Membership
Raises:	`TypeError` – If the parameter types are incorrect. `SparkApiError` – If the Cisco Spark cloud returns an error.

delete(membershipId)[source]¶

Delete a membership, by ID.

Parameters:	membershipId (basestring) – The membership ID.
Raises:	`TypeError` – If the parameter types are incorrect. `SparkApiError` – If the Cisco Spark cloud returns an error.

messages¶

class ciscosparkapi.api.messages.MessagesAPI[source]¶

Cisco Spark Messages API.

Wraps the Cisco Spark Messages API and exposes the API as native Python methods that return native Python objects.

list(roomId, mentionedPeople=None, before=None, beforeMessage=None, max=None, **request_parameters)[source]¶

Lists messages in a room.

Each message will include content attachments if present.

The list API sorts the messages in descending order by creation date.

This method supports Cisco Spark’s implementation of RFC5988 Web Linking to provide pagination support. It returns a generator container that incrementally yields all messages returned by the query. The generator will automatically request additional ‘pages’ of responses from Spark as needed until all responses have been returned. The container makes the generator safe for reuse. A new API call will be made, using the same parameters that were specified when the generator was created, every time a new iterator is requested from the container.

Parameters:	roomId (basestring) – List messages for a room, by ID. mentionedPeople (basestring) – List messages where the caller is mentioned by specifying “me” or the caller personId. before (basestring) – List messages sent before a date and time, in ISO8601 format. beforeMessage (basestring) – List messages sent before a message, by ID. max (int) – Limit the maximum number of items returned from the Spark service per request. **request_parameters – Additional request parameters (provides support for parameters that may be added in the future).
Returns:	A GeneratorContainer which, when iterated, yields the messages returned by the Cisco Spark query.
Return type:	GeneratorContainer
Raises:	`TypeError` – If the parameter types are incorrect. `SparkApiError` – If the Cisco Spark cloud returns an error.

create(roomId=None, toPersonId=None, toPersonEmail=None, text=None, markdown=None, files=None, **request_parameters)[source]¶

Post a message, and optionally a attachment, to a room.

The files parameter is a list, which accepts multiple values to allow for future expansion, but currently only one file may be included with the message.

Parameters:	roomId (basestring) – The room ID. toPersonId (basestring) – The ID of the recipient when sending a private 1:1 message. toPersonEmail (basestring) – The email address of the recipient when sending a private 1:1 message. text (basestring) – The message, in plain text. If markdown is specified this parameter may be optionally used to provide alternate text for UI clients that do not support rich text. markdown (basestring) – The message, in markdown format. files (list) – A list of public URL(s) or local path(s) to files to be posted into the room. Only one file is allowed per message. Uploaded files are automatically converted into a format that all Spark clients can render. **request_parameters – Additional request parameters (provides support for parameters that may be added in the future).
Returns:	A Message object with the details of the created message.
Return type:	Message
Raises:	`TypeError` – If the parameter types are incorrect. `SparkApiError` – If the Cisco Spark cloud returns an error. `ValueError` – If the files parameter is a list of length > 1, or if the string in the list (the only element in the list) does not contain a valid URL or path to a local file.

get(messageId)[source]¶

Get the details of a message, by ID.

Parameters:	messageId (basestring) – The ID of the message to be retrieved.
Returns:	A Message object with the details of the requested message.
Return type:	Message
Raises:	`TypeError` – If the parameter types are incorrect. `SparkApiError` – If the Cisco Spark cloud returns an error.

delete(messageId)[source]¶

Delete a message.

Parameters:	messageId (basestring) – The ID of the message to be deleted.
Raises:	`TypeError` – If the parameter types are incorrect. `SparkApiError` – If the Cisco Spark cloud returns an error.

teams¶

class ciscosparkapi.api.teams.TeamsAPI[source]¶

Cisco Spark Teams API.

Wraps the Cisco Spark Teams API and exposes the API as native Python methods that return native Python objects.

list(max=None, **request_parameters)[source]¶

List teams to which the authenticated user belongs.

This method supports Cisco Spark’s implementation of RFC5988 Web Linking to provide pagination support. It returns a generator container that incrementally yields all teams returned by the query. The generator will automatically request additional ‘pages’ of responses from Spark as needed until all responses have been returned. The container makes the generator safe for reuse. A new API call will be made, using the same parameters that were specified when the generator was created, every time a new iterator is requested from the container.

Parameters:	max (int) – Limit the maximum number of items returned from the Spark service per request. **request_parameters – Additional request parameters (provides support for parameters that may be added in the future).
Returns:	A GeneratorContainer which, when iterated, yields the teams returned by the Cisco Spark query.
Return type:	GeneratorContainer
Raises:	`TypeError` – If the parameter types are incorrect. `SparkApiError` – If the Cisco Spark cloud returns an error.

create(name, **request_parameters)[source]¶

Create a team.

The authenticated user is automatically added as a member of the team.

Parameters:	name (basestring) – A user-friendly name for the team. **request_parameters – Additional request parameters (provides support for parameters that may be added in the future).
Returns:	A Team object with the details of the created team.
Return type:	Team
Raises:	`TypeError` – If the parameter types are incorrect. `SparkApiError` – If the Cisco Spark cloud returns an error.

get(teamId)[source]¶

Get the details of a team, by ID.

Parameters:	teamId (basestring) – The ID of the team to be retrieved.
Returns:	A Team object with the details of the requested team.
Return type:	Team
Raises:	`TypeError` – If the parameter types are incorrect. `SparkApiError` – If the Cisco Spark cloud returns an error.

update(teamId, name=None, **request_parameters)[source]¶

Update details for a team, by ID.

Parameters:	teamId (basestring) – The team ID. name (basestring) – A user-friendly name for the team. **request_parameters – Additional request parameters (provides support for parameters that may be added in the future).
Returns:	A Team object with the updated Spark team details.
Return type:	Team
Raises:	`TypeError` – If the parameter types are incorrect. `SparkApiError` – If the Cisco Spark cloud returns an error.

delete(teamId)[source]¶

Delete a team.

Parameters:	teamId (basestring) – The ID of the team to be deleted.
Raises:	`TypeError` – If the parameter types are incorrect. `SparkApiError` – If the Cisco Spark cloud returns an error.

team_memberships¶

class ciscosparkapi.api.team_memberships.TeamMembershipsAPI[source]¶

Cisco Spark Team-Memberships API.

Wraps the Cisco Spark Memberships API and exposes the API as native Python methods that return native Python objects.

list(teamId, max=None, **request_parameters)[source]¶

List team memberships for a team, by ID.

This method supports Cisco Spark’s implementation of RFC5988 Web Linking to provide pagination support. It returns a generator container that incrementally yields all team memberships returned by the query. The generator will automatically request additional ‘pages’ of responses from Spark as needed until all responses have been returned. The container makes the generator safe for reuse. A new API call will be made, using the same parameters that were specified when the generator was created, every time a new iterator is requested from the container.

Parameters:	teamId (basestring) – List team memberships for a team, by ID. max (int) – Limit the maximum number of items returned from the Spark service per request. **request_parameters – Additional request parameters (provides support for parameters that may be added in the future).
Returns:	A GeneratorContainer which, when iterated, yields the team memberships returned by the Cisco Spark query.
Return type:	GeneratorContainer
Raises:	`TypeError` – If the parameter types are incorrect. `SparkApiError` – If the Cisco Spark cloud returns an error.

create(teamId, personId=None, personEmail=None, isModerator=False, **request_parameters)[source]¶

Add someone to a team by Person ID or email address.

Add someone to a team by Person ID or email address; optionally making them a moderator.

Parameters:	teamId (basestring) – The team ID. personId (basestring) – The person ID. personEmail (basestring) – The email address of the person. isModerator (bool) – Set to True to make the person a team moderator. **request_parameters – Additional request parameters (provides support for parameters that may be added in the future).
Returns:	A TeamMembership object with the details of the created team membership.
Return type:	TeamMembership
Raises:	`TypeError` – If the parameter types are incorrect. `SparkApiError` – If the Cisco Spark cloud returns an error.

get(membershipId)[source]¶

Get details for a team membership, by ID.

Parameters:	membershipId (basestring) – The team membership ID.
Returns:	A TeamMembership object with the details of the requested team membership.
Return type:	TeamMembership
Raises:	`TypeError` – If the parameter types are incorrect. `SparkApiError` – If the Cisco Spark cloud returns an error.

update(membershipId, isModerator=None, **request_parameters)[source]¶

Update a team membership, by ID.

Parameters:	membershipId (basestring) – The team membership ID. isModerator (bool) – Set to True to make the person a team moderator. **request_parameters – Additional request parameters (provides support for parameters that may be added in the future).
Returns:	A TeamMembership object with the updated Spark team membership details.
Return type:	TeamMembership
Raises:	`TypeError` – If the parameter types are incorrect. `SparkApiError` – If the Cisco Spark cloud returns an error.

delete(membershipId)[source]¶

Delete a team membership, by ID.

Parameters:	membershipId (basestring) – The team membership ID.
Raises:	`TypeError` – If the parameter types are incorrect. `SparkApiError` – If the Cisco Spark cloud returns an error.

webhooks¶

class ciscosparkapi.api.webhooks.WebhooksAPI[source]¶

Cisco Spark Webhooks API.

Wraps the Cisco Spark Webhooks API and exposes the API as native Python methods that return native Python objects.

list(max=None, **request_parameters)[source]¶

List all of the authenticated user’s webhooks.

This method supports Cisco Spark’s implementation of RFC5988 Web Linking to provide pagination support. It returns a generator container that incrementally yields all webhooks returned by the query. The generator will automatically request additional ‘pages’ of responses from Spark as needed until all responses have been returned. The container makes the generator safe for reuse. A new API call will be made, using the same parameters that were specified when the generator was created, every time a new iterator is requested from the container.

Parameters:	max (int) – Limit the maximum number of items returned from the Spark service per request. **request_parameters – Additional request parameters (provides support for parameters that may be added in the future).
Returns:	A GeneratorContainer which, when iterated, yields the webhooks returned by the Cisco Spark query.
Return type:	GeneratorContainer
Raises:	`TypeError` – If the parameter types are incorrect. `SparkApiError` – If the Cisco Spark cloud returns an error.

create(name, targetUrl, resource, event, filter=None, secret=None, **request_parameters)[source]¶

Create a webhook.

Parameters:	name (basestring) – A user-friendly name for this webhook. targetUrl (basestring) – The URL that receives POST requests for each event. resource (basestring) – The resource type for the webhook. event (basestring) – The event type for the webhook. filter (basestring) – The filter that defines the webhook scope. secret (basestring) – The secret used to generate payload signature. **request_parameters – Additional request parameters (provides support for parameters that may be added in the future).
Returns:	A Webhook object with the details of the created webhook.
Return type:	Webhook
Raises:	`TypeError` – If the parameter types are incorrect. `SparkApiError` – If the Cisco Spark cloud returns an error.

get(webhookId)[source]¶

Get the details of a webhook, by ID.

Parameters:	webhookId (basestring) – The ID of the webhook to be retrieved.
Returns:	A Webhook object with the details of the requested webhook.
Return type:	Webhook
Raises:	`TypeError` – If the parameter types are incorrect. `SparkApiError` – If the Cisco Spark cloud returns an error.

update(webhookId, name=None, targetUrl=None, **request_parameters)[source]¶

Update a webhook, by ID.

Parameters:	webhookId (basestring) – The webhook ID. name (basestring) – A user-friendly name for this webhook. targetUrl (basestring) – The URL that receives POST requests for each event. **request_parameters – Additional request parameters (provides support for parameters that may be added in the future).
Returns:	A Webhook object with the updated Spark webhook details.
Return type:	Webhook
Raises:	`TypeError` – If the parameter types are incorrect. `SparkApiError` – If the Cisco Spark cloud returns an error.

delete(webhookId)[source]¶

Delete a webhook, by ID.

Parameters:	webhookId (basestring) – The ID of the webhook to be deleted.
Raises:	`TypeError` – If the parameter types are incorrect. `SparkApiError` – If the Cisco Spark cloud returns an error.

organizations¶

class ciscosparkapi.api.organizations.OrganizationsAPI[source]¶

Cisco Spark Organizations API.

Wraps the Cisco Spark Organizations API and exposes the API as native Python methods that return native Python objects.

list(max=None, **request_parameters)[source]¶

List Organizations.

This method supports Cisco Spark’s implementation of RFC5988 Web Linking to provide pagination support. It returns a generator container that incrementally yields all objects returned by the query. The generator will automatically request additional ‘pages’ of responses from Spark as needed until all responses have been returned. The container makes the generator safe for reuse. A new API call will be made, using the same parameters that were specified when the generator was created, every time a new iterator is requested from the container.

Parameters:	max (int) – Limit the maximum number of items returned from the Spark service per request. **request_parameters – Additional request parameters (provides support for parameters that may be added in the future).
Returns:	A GeneratorContainer which, when iterated, yields the organizations returned by the Cisco Spark query.
Return type:	GeneratorContainer
Raises:	`TypeError` – If the parameter types are incorrect. `SparkApiError` – If the Cisco Spark cloud returns an error.

get(orgId)[source]¶

Get the details of an Organization, by ID.

Parameters:	orgId (basestring) – The ID of the Organization to be retrieved.
Returns:	An Organization object with the details of the requested organization.
Return type:	Organization
Raises:	`TypeError` – If the parameter types are incorrect. `SparkApiError` – If the Cisco Spark cloud returns an error.

licenses¶

class ciscosparkapi.api.licenses.LicensesAPI[source]¶

Cisco Spark Licenses API.

Wraps the Cisco Spark Licenses API and exposes the API as native Python methods that return native Python objects.

list(orgId=None, max=None, **request_parameters)[source]¶

List all licenses for a given organization.

If no orgId is specified, the default is the organization of the authenticated user.

This method supports Cisco Spark’s implementation of RFC5988 Web Linking to provide pagination support. It returns a generator container that incrementally yields all objects returned by the query. The generator will automatically request additional ‘pages’ of responses from Spark as needed until all responses have been returned. The container makes the generator safe for reuse. A new API call will be made, using the same parameters that were specified when the generator was created, every time a new iterator is requested from the container.

Parameters:	orgId (basestring) – Specify the organization, by ID. max (int) – Limit the maximum number of items returned from the Spark service per request. **request_parameters – Additional request parameters (provides support for parameters that may be added in the future).
Returns:	A GeneratorContainer which, when iterated, yields the licenses returned by the Cisco Spark query.
Return type:	GeneratorContainer
Raises:	`TypeError` – If the parameter types are incorrect. `SparkApiError` – If the Cisco Spark cloud returns an error.

get(licenseId)[source]¶

Get the details of a License, by ID.

Parameters:	licenseId (basestring) – The ID of the License to be retrieved.
Returns:	A License object with the details of the requested License.
Return type:	License
Raises:	`TypeError` – If the parameter types are incorrect. `SparkApiError` – If the Cisco Spark cloud returns an error.

roles¶

class ciscosparkapi.api.roles.RolesAPI[source]¶

Cisco Spark Roles API.

Wraps the Cisco Spark Roles API and exposes the API as native Python methods that return native Python objects.

list(max=None, **request_parameters)[source]¶

List all roles.

This method supports Cisco Spark’s implementation of RFC5988 Web Linking to provide pagination support. It returns a generator container that incrementally yields all objects returned by the query. The generator will automatically request additional ‘pages’ of responses from Spark as needed until all responses have been returned. The container makes the generator safe for reuse. A new API call will be made, using the same parameters that were specified when the generator was created, every time a new iterator is requested from the container.

Parameters:	max (int) – Limit the maximum number of items returned from the Spark service per request. **request_parameters – Additional request parameters (provides support for parameters that may be added in the future).
Returns:	A GeneratorContainer which, when iterated, yields the roles returned by the Cisco Spark query.
Return type:	GeneratorContainer
Raises:	`TypeError` – If the parameter types are incorrect. `SparkApiError` – If the Cisco Spark cloud returns an error.

get(roleId)[source]¶

Get the details of a Role, by ID.

Parameters:	roleId (basestring) – The ID of the Role to be retrieved.
Returns:	A Role object with the details of the requested Role.
Return type:	Role
Raises:	`TypeError` – If the parameter types are incorrect. `SparkApiError` – If the Cisco Spark cloud returns an error.

events¶

class ciscosparkapi.api.events.EventsAPI[source]¶

Cisco Spark Events API.

Wraps the Cisco Spark Events API and exposes the API as native Python methods that return native Python objects.

list(resource=None, type=None, actorId=None, _from=None, to=None, max=None, **request_parameters)[source]¶

List events.

List events in your organization. Several query parameters are available to filter the response.

Note: from is a keyword in Python and may not be used as a variable name, so we had to use _from instead.

This method supports Cisco Spark’s implementation of RFC5988 Web Linking to provide pagination support. It returns a generator container that incrementally yields all events returned by the query. The generator will automatically request additional ‘pages’ of responses from Spark as needed until all responses have been returned. The container makes the generator safe for reuse. A new API call will be made, using the same parameters that were specified when the generator was created, every time a new iterator is requested from the container.

Parameters:	resource (basestring) – Limit results to a specific resource type. Possible values: “messages”, “memberships”. type (basestring) – Limit results to a specific event type. Possible values: “created”, “updated”, “deleted”. actorId (basestring) – Limit results to events performed by this person, by ID. _from (basestring) – Limit results to events which occurred after a date and time, in ISO8601 format (yyyy-MM-dd’T’HH:mm:ss.SSSZ). to (basestring) – Limit results to events which occurred before a date and time, in ISO8601 format (yyyy-MM-dd’T’HH:mm:ss.SSSZ). max (int) – Limit the maximum number of items returned from the Spark service per request. **request_parameters – Additional request parameters (provides support for parameters that may be added in the future).
Returns:	A GeneratorContainer which, when iterated, yields the events returned by the Cisco Spark query.
Return type:	GeneratorContainer
Raises:	`TypeError` – If the parameter types are incorrect. `SparkApiError` – If the Cisco Spark cloud returns an error.

get(eventId)[source]¶

Get the details for an event, by event ID.

Parameters:	eventId (basestring) – The ID of the event to be retrieved.
Returns:	A event object with the details of the requested room.
Return type:	Event
Raises:	`TypeError` – If the parameter types are incorrect. `SparkApiError` – If the Cisco Spark cloud returns an error.

access_tokens¶

class ciscosparkapi.api.access_tokens.AccessTokensAPI[source]¶

Cisco Spark Access-Tokens API.

Wraps the Cisco Spark Access-Tokens API and exposes the API as native Python methods that return native Python objects.

base_url¶: The base URL the API endpoints.

timeout¶: Timeout in seconds for the API requests.

get(client_id, client_secret, code, redirect_uri)[source]¶

Exchange an Authorization Code for an Access Token.

Exchange an Authorization Code for an Access Token that can be used to invoke the APIs.

Parameters:	client_id (basestring) – Provided when you created your integration. client_secret (basestring) – Provided when you created your integration. code (basestring) – The Authorization Code provided by the user OAuth process. redirect_uri (basestring) – The redirect URI used in the user OAuth process.
Returns:	An AccessToken object with the access token provided by the Cisco Spark cloud.
Return type:	ciscosparkapi.AccessToken
Raises:	`TypeError` – If the parameter types are incorrect. `SparkApiError` – If the Cisco Spark cloud returns an error.

refresh(client_id, client_secret, refresh_token)[source]¶

Return a refreshed Access Token from the provided refresh_token.

Parameters:	client_id (basestring) – Provided when you created your integration. client_secret (basestring) – Provided when you created your integration. refresh_token (basestring) – Provided when you requested the Access Token.
Returns:	With the access token provided by the Cisco Spark cloud.
Return type:	AccessToken
Raises:	`TypeError` – If the parameter types are incorrect. `SparkApiError` – If the Cisco Spark cloud returns an error.

Exceptions¶

exception ciscosparkapi.ciscosparkapiException[source]¶

Bases: Exception

Base class for all ciscosparkapi package exceptions.

exception ciscosparkapi.SparkApiError[source]¶

Bases: ciscosparkapi.exceptions.ciscosparkapiException

Errors returned by requests to the Cisco Spark cloud APIs.

request = None¶: The requests.PreparedRequest of the API call.

response = None¶: The requests.Response object returned from the API call.

exception ciscosparkapi.SparkRateLimitError[source]¶

Bases: ciscosparkapi.exceptions.SparkApiError

Cisco Spark Rate-Limit exceeded Error.

retry_after = None¶

The Retry-After time period (in seconds) provided by Cisco Spark.

Defaults to 15 seconds if the response Retry-After header isn’t present in the response headers, and defaults to a minimum wait time of 1 second if Spark returns a Retry-After header of 0 seconds.

Spark Data Objects¶

Person¶

class ciscosparkapi.Person[source]¶

Cisco Spark Person data model.

avatar¶: URL to the person’s avatar in PNG format.

created¶: The date and time the person was created.

displayName¶: Full name of the person.

emails¶: Email address(es) of the person.

firstName¶: First name of the person.

id¶: The person’s unique ID.

invitePending¶: Person has been sent an invite, but hasn’t responded.

json_data¶: A copy of the Spark data object’s JSON data (OrderedDict).

lastActivity¶: The date and time of the person’s last activity.

lastName¶: Last name of the person.

licenses¶: Licenses allocated to the person.

loginEnabled¶: Person is allowed to login.

nickName¶: ‘Nick name’ or preferred short name of the person.

orgId¶: ID of the organization to which this person belongs.

roles¶: Roles of the person.

status¶: The person’s current status.

to_dict()¶: Convert the Spark data to a dictionary.

to_json(**kwargs)¶

Convert the Spark data to JSON.

Any keyword arguments provided are passed through the Python JSON encoder.

type¶: The type of object returned by Cisco Spark (should be person).

Room¶

class ciscosparkapi.Room[source]¶

Cisco Spark Room data model.

created¶: The date and time when the room was created.

creatorId¶: The ID of the person who created the room.

id¶: The rooms’s unique ID.

isLocked¶: Whether or not the room is locked and controlled by moderator(s).

json_data¶: A copy of the Spark data object’s JSON data (OrderedDict).

lastActivity¶: The date and time when the room was last active.

teamId¶: The ID for the team with which this room is associated.

title¶: A user-friendly name for the room.

to_dict()¶: Convert the Spark data to a dictionary.

to_json(**kwargs)¶

Convert the Spark data to JSON.

Any keyword arguments provided are passed through the Python JSON encoder.

type¶: The type of room (i.e. ‘group’, ‘direct’ etc.).

Membership¶

class ciscosparkapi.Membership[source]¶

Cisco Spark Membership data model.

created¶: The date and time the membership was created.

id¶: The membership’s unique ID.

isModerator¶: Person is a moderator for the room.

isMonitor¶: Person is a monitor for the room.

json_data¶: A copy of the Spark data object’s JSON data (OrderedDict).

personDisplayName¶: The display name of the person.

personEmail¶: The email address of the person.

personId¶: The ID of the person.

personOrgId¶: The ID of the organization that the person is associated with.

roomId¶: The ID of the room.

to_dict()¶: Convert the Spark data to a dictionary.

to_json(**kwargs)¶

Convert the Spark data to JSON.

Any keyword arguments provided are passed through the Python JSON encoder.

Message¶

class ciscosparkapi.Message[source]¶

Cisco Spark Message data model.

created¶: The date and time the message was created.

files¶: Files attached to the the message (list of URLs).

html¶: The message, in HTML format.

id¶: The message’s unique ID.

json_data¶: A copy of the Spark data object’s JSON data (OrderedDict).

markdown¶: The message, in markdown format.

mentionedPeople¶: The list of IDs of people mentioned in the message.

personEmail¶: The email address of the sender.

personId¶: The person ID of the sender.

roomId¶: The ID of the room.

roomType¶: The type of room (i.e. ‘group’, ‘direct’ etc.).

text¶: The message, in plain text.

to_dict()¶: Convert the Spark data to a dictionary.

to_json(**kwargs)¶

Convert the Spark data to JSON.

Any keyword arguments provided are passed through the Python JSON encoder.

Team¶

class ciscosparkapi.Team[source]¶

Cisco Spark Team data model.

created¶: The date and time the team was created.

creatorId¶: The ID of the person who created the team.

id¶: The team’s unique ID.

json_data¶: A copy of the Spark data object’s JSON data (OrderedDict).

name¶: A user-friendly name for the team.

to_dict()¶: Convert the Spark data to a dictionary.

to_json(**kwargs)¶

Convert the Spark data to JSON.

Any keyword arguments provided are passed through the Python JSON encoder.

Team Membership¶

class ciscosparkapi.TeamMembership[source]¶

Cisco Spark Team-Membership data model.

created¶: The date and time the team membership was created.

id¶: The team membership’s unique ID.

isModerator¶: Person is a moderator for the team.

json_data¶: A copy of the Spark data object’s JSON data (OrderedDict).

personDisplayName¶: The display name of the person.

personEmail¶: The email address of the person.

personId¶: The ID of the person.

personOrgId¶: The ID of the organization that the person is associated with.

teamId¶: The ID of the team.

to_dict()¶: Convert the Spark data to a dictionary.

to_json(**kwargs)¶

Convert the Spark data to JSON.

Any keyword arguments provided are passed through the Python JSON encoder.

Webhook¶

class ciscosparkapi.Webhook[source]¶

Cisco Spark Webhook data model.

appId¶: Identifies the application that added the webhook.

created¶: Creation date and time in ISO8601 format.

createdBy¶: The ID of the person that added the webhook.

event¶: The event type for the webhook.

filter¶: The filter that defines the webhook scope.

id¶: Webhook ID.

json_data¶: A copy of the Spark data object’s JSON data (OrderedDict).

name¶: A user-friendly name for this webhook.

orgId¶: The ID of the organization that owns the webhook.

ownedBy¶

Indicates if the webhook is owned by the org or the creator.

Webhooks owned by the creator can only receive events that are accessible to the creator of the webhook. Those owned by the organization will receive events that are visible to anyone in the organization.

resource¶: The resource type for the webhook.

secret¶: Secret used to generate payload signature.

status¶

Indicates if the webhook is active.

A webhook that cannot reach your URL is disabled.

targetUrl¶: The URL that receives POST requests for each event.

to_dict()¶: Convert the Spark data to a dictionary.

to_json(**kwargs)¶

Convert the Spark data to JSON.

Any keyword arguments provided are passed through the Python JSON encoder.

Webhook Event¶

class ciscosparkapi.WebhookEvent[source]¶

Cisco Spark Webhook-Events data model.

actorId¶: The ID of the person that caused the webhook to be sent.

appId¶: Identifies the application that added the webhook.

createdBy¶: The ID of the person that added the webhook.

data¶: The data for the resource that triggered the webhook.

event¶: The event type for the webhook.

filter¶: The filter that defines the webhook scope.

id¶: Webhook ID.

json_data¶: A copy of the Spark data object’s JSON data (OrderedDict).

name¶: A user-friendly name for this webhook.

orgId¶: The ID of the organization that owns the webhook.

ownedBy¶

Indicates if the webhook is owned by the org or the creator.

Webhooks owned by the creator can only receive events that are accessible to the creator of the webhook. Those owned by the organization will receive events that are visible to anyone in the organization.

resource¶: The resource type for the webhook.

status¶

Indicates if the webhook is active.

A webhook that cannot reach your URL is disabled.

to_dict()¶: Convert the Spark data to a dictionary.

to_json(**kwargs)¶

Convert the Spark data to JSON.

Any keyword arguments provided are passed through the Python JSON encoder.

Organization¶

class ciscosparkapi.Organization[source]¶

Cisco Spark Organization data model.

created¶: Creation date and time in ISO8601 format.

displayName¶: The human-friendly display name of the Organization.

id¶: The unique ID for the Organization.

json_data¶: A copy of the Spark data object’s JSON data (OrderedDict).

to_dict()¶: Convert the Spark data to a dictionary.

to_json(**kwargs)¶

Convert the Spark data to JSON.

Any keyword arguments provided are passed through the Python JSON encoder.

License¶

class ciscosparkapi.License[source]¶

Cisco Spark License data model.

consumedUnits¶: The total number of license units consumed.

id¶: The unique ID for the License.

json_data¶: A copy of the Spark data object’s JSON data (OrderedDict).

name¶: The name of the License.

to_dict()¶: Convert the Spark data to a dictionary.

to_json(**kwargs)¶

Convert the Spark data to JSON.

Any keyword arguments provided are passed through the Python JSON encoder.

totalUnits¶: The total number of license units.

Role¶

class ciscosparkapi.Role[source]¶

Cisco Spark Role data model.

id¶: The unique ID for the Role.

json_data¶: A copy of the Spark data object’s JSON data (OrderedDict).

name¶: The name of the Role.

to_dict()¶: Convert the Spark data to a dictionary.

to_json(**kwargs)¶

Convert the Spark data to JSON.

Any keyword arguments provided are passed through the Python JSON encoder.

Event¶

class ciscosparkapi.Event[source]¶

Cisco Spark Event data model.

actorId¶: The ID of the person that performed this event.

created¶: The date and time the event was performed.

data¶: The event resource data.

id¶: Event ID.

json_data¶: A copy of the Spark data object’s JSON data (OrderedDict).

resource¶: The event resource type (messagess, memberships).

to_dict()¶: Convert the Spark data to a dictionary.

to_json(**kwargs)¶

Convert the Spark data to JSON.

Any keyword arguments provided are passed through the Python JSON encoder.

type¶: The event type (created, updated, deleted).

Access Token¶

class ciscosparkapi.AccessToken[source]¶

Cisco Spark Access-Token data model.

access_token¶: Cisco Spark access token.

expires_in¶: Access token expiry time (in seconds).

json_data¶: A copy of the Spark data object’s JSON data (OrderedDict).

refresh_token¶: Refresh token used to request a new/refreshed access token.

refresh_token_expires_in¶: Refresh token expiry time (in seconds).

to_dict()¶: Convert the Spark data to a dictionary.

to_json(**kwargs)¶

Convert the Spark data to JSON.

Any keyword arguments provided are passed through the Python JSON encoder.