TPEN Services API Documentation

POST/project/create 🔐

Description: Create a new project. This is a high-skill maneuver requiring a complete project object.

Request Body:

{
    "label": "string",
    "metadata": [ { Metadata } ],
    "layers": [ { Layer } ],
    "manifests": [ "URIs<Manifest>" ],
    "creator": "URI<Agent>",
    "group": "hexstring"
}

Responses:

Note: The Location header of a successful response contains the Project ID.

POST/import?createFrom="URL" 🔐

Description: Create a new project by importing a web resource.

Request Body:

{
    "url": "URL<IIIF:Manifest>"
}

Responses:

Note: The Location header contains the Project ID. The project will be created with the label and metadata of the imported resource.

GET/project/:id 🔐

Description: Retrieve a project by ID.

Parameters:

• id: ID of the project

Responses:

Success Response Example:

{
    "id": "string",
    "label": "string",
    "metadata": [ { Metadata } ],
    "creator": "URI<Agent>",
    "layers": [ { Layer } ],
    "manifests": [ "URIs<Manifest>" ],
    "group": "hexstring",
    "tools": [ "string" ],
    "options": { OptionsMap }
}

Note: The response is not a complete Project data object, but a projection designed for use in the client interface.

POST/project/:projectId/invite-member 🔐

Description: Invite a user to a project. If the user does not have a TPEN account, they will be sent an email invitation.

Parameters:

• projectId: ID of the project as a hexstring or the Project slug

Request Body:

{
    "email": "string",
    "roles": ["string"] | "string"
}

• email: The email address of the user to invite
• roles: The roles of the user in the project as an array or space-delimited string

Responses:

Note: This API is not able to track the status of the invitation. Email addresses that fail to be delivered or are rejected by the recipient will not be reported.

POST/project/:projectId/remove-member 🔐

Description: Remove a user from a project group.

Parameters:

• projectId: ID of the project

Request Body:

{
    "userID": "string"
}

Responses:

Note: This removes a user and their roles from the project. The user will no longer have access to the project, but their annotations will remain with full attribution.

PUT/project/:projectId/collaborator/:collaboratorId/setRoles 🔐

Description: Set the roles of a User in a project, replacing all currently defined roles.

Parameters:

• projectId: ID of the project
• collaboratorId: ID of the collaborator

Request Body:

{
    "roles": ["string"] | "string"
}

Responses:

Note: The User requesting this action must have permissions to set roles for the collaborator. The OWNER role cannot be set using this endpoint.

POST/project/:projectId/switch/owner 🔐

Description: Transfer ownership of a project to another user.

Parameters:

• projectId: ID of the project

Request Body:

{
    "newOwnerId": "hexstring"
}

Responses:

Note: The User requesting this action must be the current owner of the project. The OWNER role will be removed from the current owner and assigned to the new owner. The new owner must be a member of the project. If the current owner has no other roles, the CONTRIBUTOR role will be assigned to them.

POST/project/:projectId/setCustomRoles 🔐

Description: Set custom roles for a Project group. Custom roles must be provided as a JSON object with keys as roles and values as arrays of permissions or space-delimited strings.

Parameters:

• projectId: ID of the project

Request Body:

{
    "roles": {
        "roleName": ["permission1", "permission2"] | "space-delimited permissions"
    }
}

Responses:

Note: The User requesting this action must have permissions to update roles. Default roles cannot be modified using this endpoint. Custom roles can be complicated and there is more detailed description of their use in the Cookbook.

GET/my/profile 🔐

Description: Retrieve the profile of the authenticated user.

Responses:

Success Response Example:

{
    "_id": "hexstring",
    "_sub": "string",
    "agent": "URI<Agent>",
    "email": "string",
    "profile": {
        "displayName": "string",
        "custom": Any
    },
    "name": "string"
}

Note: Users can always see and manipulate their own profile. The profile object is a projection of the full user object.

GET/my/projects 🔐

Description: Retrieve a list of projects the authenticated user is a member of.

Responses:

Success Response Example:

[
    {
        "_id": "hexstring",
        "label": "string",
        "roles": ["string"]
    }, ...
]

Note: The response is a list of projects the user is a member of regardless of the permissions afforded to them in each project.

GET/user/:id

Description: Retrieve the public profile of a user.

Parameters:

• id: ID of the user

Responses:

Success Response Example:

{
    "_id": "hexstring",
    "displayName": "string",
    "custom": Any
}

Note: The response is a projection of the full user object. The public profile is available to all users and serialized into this response with whatever the user has chosen to share. The custom field is not an actual property - it is a placeholder for any additional fields the user has added to their profile. The displayName and _id fields are always present.

POST/project/:projectId/layer 🔐

Description: Create a new layer within a project.

Parameters:

• projectId: ID of the project

Request Body:

{
    "label": "string",
    "canvases": ["string"]
}

Responses:

Success Response Example:

{
    "id": "string",
    "label": "string",
    "pages": ["string"]
}

Note: Requests without at least one canvas are considered invalid.

PUT/project/:projectId/layer/:layerId 🔐

Description: Update an existing layer within a project.

Parameters:

• projectId: ID of the project
• layerId: ID of the layer

Request Body:

{
    "label": "string",
    "canvases": ["string"]
}

Responses:

Success Response Example:

{
    "id": "string",
    "label": "string",
    "pages": ["string"]
}

Note: You may not empty the canvases of an existing layer. If the canvases property is an empty array the request will be treated as if it did not contain the canvases property at all.

GET/project/:projectId/layer/:layerId

Description: Get an existing layer within a project.

Parameters:

• projectId: ID of the project
• layerId: ID of the layer

Responses:

Success Response Example:

{
    "@context": "string",
    "id": "string",
    "type": "AnnotationCollection",
    "label": {
        "none":[
            "TPEN3 Layer"
        ]
    },
    "total": "integer",
    "first": "string",
    "last": "string"
}

GET/project/:projectId/layer/:layerId/page/:pageid

GET/project/:projectId/page/:pageid

Description: Get an existing page within a project.

Parameters:

• projectId: ID of the project
• layerId: Optional. ID of the layer
• pageId: The ID of the page

Responses:

Success Response Example:

{
    "@context": "string",
    "id": "string",
    "type": "AnnotationPage",
    "label": {
        "none":[
            "TPEN3 Page"
        ]
    },
    "target": "string",
    "items":[ {"type": "Canvas"} ],
    "prev": "string",
    "next": "string"
}