apiary.apib

FORMAT: 1A


# Superdesk API


Superdesk is an open source end-to-end news creation, production, curation, distribution and publishing platform developed and maintained 
by Sourcefabric with the sole purpose of making the best possible software for journalism. 

This is the offical documentation of Superdesk API used by Superdesk application. It features all the resources to 
 - manage a newsroom (i.e. users, desks, stages etc)
 - manage stories (i.e. templates, stories, multimedia etc)
 - manage distribution (i.e. subscribers, filters, destinations etc) 

---

## Before You Begin

The base URI for all requests is http://{{host}/api where host will be the host address where the server runs.

To run the server locally please check [Superdesk](https://github.com/superdesk/superdesk) repo for all the information

---

## Features

Below is a list of some of the main features that any Superdesk APIs can expose. 

 - (Filtering)[https://docs.python-eve.org/en/stable/features.html#filtering]
 - (Sorting)[https://docs.python-eve.org/en/stable/features.html#sorting]
 - (Pagination)[https://docs.python-eve.org/en/stable/features.html#pagination]
 - (HATEOAS)[https://docs.python-eve.org/en/stable/features.html#hateoas]

---

## PATCH and DELETE actions

Patch and Delte actions will require a header `If-Match` with the _etag_ value of the resource


# Group Authentication

<!-- include(endpoints/configuration/auth.apib) -->
    
# Group All Resources

List of resources related to questions in the API.

<!-- include(endpoints/all-resources.apib) -->

# Group User Management

<!-- include(endpoints/configuration/users.apib) -->

# Group Roles Management

<!-- include(endpoints/configuration/roles.apib) -->

# Group Preference Management

<!-- include(endpoints/configuration/preferences.apib) -->

# Group Session Management

<!-- include(endpoints/configuration/sessions.apib) -->

# Group Stage Management

<!-- include(endpoints/configuration/stages.apib) -->

# Group Desk Management

<!-- include(endpoints/configuration/desks.apib) -->

# Group Vocabularies

<!-- include(endpoints/configuration/vocabularies.apib) -->

# Group Routing Schemes

<!-- include(endpoints/configuration/routing-schemes.apib) -->

# Group Dictionaries

<!-- include(endpoints/configuration/dictionaries.apib) -->

# Group Rule Sets

<!-- include(endpoints/configuration/rule-sets.apib) -->

# Group Audits

<!-- include(endpoints/configuration/audits.apib) -->

# Group Validators

<!-- include(endpoints/configuration/validators.apib) -->

# Group Workspaces

<!-- include(endpoints/configuration/workspaces.apib) -->

# Group Concept Items

<!-- include(endpoints/configuration/concept-items.apib) -->

# Group Allowed Values

<!-- include(endpoints/configuration/allowed-values.apib) -->

# Group Backend Meta

<!-- include(endpoints/configuration/backend-meta.apib) -->

# Group Closed Desks

<!-- include(endpoints/configuration/closed-desks.apib) -->

# Group Content Templates

<!-- include(endpoints/configuration/content-templates.apib) -->

# Group Content Types

<!-- include(endpoints/configuration/content-types.apib) -->

# Group Internal Destinations

<!-- include(endpoints/configuration/internal-destinations.apib) -->

# Group Search Providers

<!-- include(endpoints/configuration/search-providers.apib) -->

# Group Client Config

<!-- include(endpoints/configuration/client-config.apib) -->

# Group Server Configurations

<!-- include(endpoints/configuration/config.apib) -->

# Group Archive

<!-- include(endpoints/content/archive.apib) -->

# Group Archive Autosave

<!-- include(endpoints/content/archive-autosave.apib) -->

# Group Archive History

<!-- include(endpoints/content/archive-history.apib) -->

# Group Comments

<!-- include(endpoints/content/comments.apib) -->

# Group Archive Publishing

<!-- include(endpoints/content/archive-publish.apib) -->

# Group Highlights

<!-- include(endpoints/content/highlights.apib) -->

# Group Archived

<!-- include(endpoints/content/archived.apib) -->

# Group Attachments

<!-- include(endpoints/content/attachments.apib) -->

# Group Export

<!-- include(endpoints/content/export.apib) -->

# Group Macros

<!-- include(endpoints/content/macros.apib) -->

# Group Mark For Desks

<!-- include(endpoints/content/mark-for-desks.apib) -->

# Group Spikes

<!-- include(endpoints/content/spikes.apib) -->

# Group Spellcheck

<!-- include(endpoints/content/spell-check.apib) -->

# Group Uploads

<!-- include(endpoints/content/uploads.apib) -->

# Group Media Editor

Media Editor do requested transformations on a media (images only for now).

<!-- include(endpoints/content/media-editor.apib) -->

# Group Picture Crop

<!-- include(endpoints/content/picture-crop.apib) -->

# Group Picture Renditions

<!-- include(endpoints/content/picture-renditions.apib) -->

# Group Suggestion

<!-- include(endpoints/content/suggestions.apib) -->

# Group Tasks

<!-- include(endpoints/content/tasks.apib) -->

# Group Published Items

<!-- include(endpoints/content/published.apib) -->

# Group Saved Searches

<!-- include(endpoints/content/saved-searches.apib) -->

# Group Workqueue

<!-- include(endpoints/content/workqueue.apib) -->

# Group Contacts

<!-- include(endpoints/content/contacts.apib) -->


# Group Search

<!-- include(endpoints/content/search.apib) -->



# Group Ingest Provider

List of resources related to ingest providers in the API.

<!-- include(endpoints/ingest/ingest-provider.apib) -->

# Group Ingest

<!-- include(endpoints/ingest/ingest.apib) -->

# Group Feeding Services

<!-- include(endpoints/ingest/feeding-services.apib) -->

# Group Filter Conditions

<!-- include(endpoints/distribution/filter-conditions.apib) -->

# Group Content Filters

<!-- include(endpoints/distribution/content-filters.apib) -->

# Group Formatters

<!-- include(endpoints/distribution/formatters.apib) -->

# Group Products

<!-- include(endpoints/distribution/products.apib) -->

# Group Publish Queue

<!-- include(endpoints/distribution/publish-queue.apib) -->

# Group Content Api Items

<!-- include(endpoints/content-api/items.apib) -->

# Group Content Api Search

<!-- include(endpoints/content-api/search-capi.apib) -->



# Group Agenda

<!-- include(endpoints/planning/agenda.apib) -->

# Group Events

<!-- include(endpoints/planning/events.apib) -->

# Group Event Autosave

<!-- include(endpoints/planning/events-autosave.apib) -->

# Group Event Files

<!-- include(endpoints/planning/events-files.apib) -->

# Group Event History

<!-- include(endpoints/planning/events-history.apib) -->

# Group Event Planning Search

<!-- include(endpoints/planning/events-planning-search.apib) -->

# Group Event Planning Filters

<!-- include(endpoints/planning/events-planning-filters.apib) -->


# Group Planning

<!-- include(endpoints/planning/planning.apib) -->

# Group Planning Autosave

<!-- include(endpoints/planning/planning-autosave.apib) -->

# Group Planning Export Templates

<!-- include(endpoints/planning/planning-export-templates.apib) -->

# Group Planning Article Export

<!-- include(endpoints/planning/planning-article-export.apib) -->

# Group Planning Download

<!-- include(endpoints/planning/planning-download.apib) -->

# Group Planning Validator

<!-- include(endpoints/planning/planning-validator.apib) -->

# Group Planning Types

<!-- include(endpoints/planning/planning-types.apib) -->

# Group Planning Files

<!-- include(endpoints/planning/planning-files.apib) -->

# Group Planning History

<!-- include(endpoints/planning/planning-history.apib) -->

# Group Featured Planning Items

<!-- include(endpoints/planning/planning-featured.apib) -->

# Group Planning Search

<!-- include(endpoints/planning/planning-search.apib) -->



# Group Assignments

**The life cycle of an Assignment**

- A Coverage can be assigned to a desk or to a desk and user. From within planning, for example, an editor may decide to assign a coverage to a desk or bureau and allow them to decide which staffer does the work, or the editor may decide to assign directly to a user.
 
- If a coverage is assigned to a desk, a user needs to be a member of that desk in order to see it in their list of assignments, and the item will be created on that desk.

- The work for a coverage assignment should always be created on a desk. It should not be possible to fulfill a coverage within a personal workspace

- The default (initial) state of an assignment is ‘assigned’ This means that the Coverage is assigned to workflow but work has not started.

- Once an associated (linked) content item is created, the assignment status is changed to “in progress”. 

- When an assignment is configured with a ‘coverage provider’ the ‘start working’ action to create a new content item will not be available.

- When an ‘in progress’ text assignment is completed by a user on an authoring desk they will then send the item to a production desk. In this workflow case, the assignment status will change to ‘submitted’ and there will also be a change of desk assignment so that the story assignment now appears in the assignment list for the production desk (with no [assigned_user]). When a user on the production desk then edits the submitted story, the assignment status will again change to ‘in progress’ and the [assigned_user] value will reflect the current lock user.

- Once/When an item linked to an Assignment is published, the assignment status is changed to “completed”.

- A User can also manually mark an assignment as complete.

- Once an assignment has been completed, no further actions are available against it. For example, a User cannot “re-assign” an assignment if it has already been completed. 

- If a user who has accepted an assignment partially completes it before reassigning it back to the desk (or to another user), any content that may have already been created from the Assignment is left untouched. This might for example occur if a user who is working on an assignment needs to switch to another, leaving their original assignment to be picked up by someone else.

- A coverage (and its related Assignment) can be cancelled. If there has been any content already generated for a cancelled coverage the content will be left ‘as is’ in the system, but with all references to planning removed



<!-- include(endpoints/planning/assignments.apib) -->

# Group Assignments History

<!-- include(endpoints/planning/assignments-history.apib) -->

# Group Locations

<!-- include(endpoints/planning/locations.apib) -->

# Group Published Planning

<!-- include(endpoints/planning/published-planning.apib) -->