Skip to main content

Utility Endpoints

Utility endpoints provide specialized functionality for common integration tasks including direct asset navigation, file management, and project member queries.

assetdetail.v1 - Asset Permalinks​

This endpoint provides permalink URLs for directly launching the Details view for any asset in Digital.ai Agility. The endpoint supports specifying an asset by OID Token or Number.

FieldValue
URL Form<Server Base URI>/assetdetail.v1?oid=<OID> or <Server Base URI>/assetdetail.v1?number=<Number>
AuthenticationApplication
HTTP Request VerbGET
Response Content Typetext/html (redirect)

Query Parameters​

  • oid - The OID Token of the asset (e.g., Story:1010)
  • number - The display number of the asset (e.g., S-01001)

Use either oid or number, not both.

Examples​

Open Details View with OID Token​

Request the Details view for a Story by specifying its OID Token:

<Server Base URI>/assetdetail.v1?oid=Story:1010

Open Details View with Asset Number​

Request the Details view for a Story by specifying its Number:

<Server Base URI>/assetdetail.v1?number=S-01001

Use Cases​

  • Create deep links in external systems (wikis, portals, emails)
  • Provide direct navigation from integration tools
  • Build custom dashboards with clickable asset references
  • Generate notification emails with asset links

attachments.img - File Attachments​

The attachments.img endpoint handles upload and download of attachment file data, supporting both binary and text files.

FieldValue
URL Form<Server Base URI>/attachments.img/<attachment_id>
AuthenticationApplication
HTTP Request VerbGET, POST
Response Content TypeVaries (based on file type)

HTTP Verbs​

HTTP GET​

Download an existing attachment by providing the attachment ID.

HTTP POST​

Upload a new attachment with multipart/form-data encoding.

Use Cases​

  • Attach screenshots or documents to work items
  • Download test result files
  • Upload requirement specifications
  • Manage design assets for stories
  • Store build artifacts or logs

API/ProjectRoles - Project Member Queries​

The project roles endpoint provides the capability to query project member information. You can query by project to see all members, or query by member to see all their project assignments.

FieldValue
URL Form<Server Base URI>/API/ProjectRoles
AuthenticationApplication
HTTP Request VerbGET
Response Content Typeapplication/json

Capabilities​

  • Query members by project
  • Query projects by member
  • Retrieve member role information
  • Access member email addresses
  • Identify project administrators

The Story​

As a Digital.ai Agility administrator, you need a way to automate project member access so that you can reduce time investigating who the project admin is on a project. Currently, a member fills out a SharePoint form to request project access. You must then log in to Agility and research who the project admin is, then email that project admin with the member information of who is asking. The project admin evaluates whether that member needs access to the project. With 2,000 members, this becomes a never-ending task as projects evolve.

The Solution​

With the project member endpoint, a form that resides on SharePoint (or any system) can programmatically access who the members are on a project and their roles. The member's email address is also returned, which can then be used to alert the project admin of the request with the information provided.

RAML Documentation​

The project member endpoint uses RAML (RESTful API Modeling Language). Visit the endpoint directly to discover its capabilities and queryable information:

<Server Base URI>/API/ProjectRoles

Use Cases​

  • Automate project access request workflows
  • Build custom project directory interfaces
  • Generate project team rosters
  • Send notifications to project administrators
  • Audit project membership across the organization
  • Integrate with identity management systems

Example Workflow​

Automated Access Request Process:

  1. User submits access request via web form
  2. System queries API/ProjectRoles?project=<OID> to get project members
  3. System identifies project administrators from role information
  4. Automated email sent to project admin with requester details
  5. Project admin approves or denies via integration link
  6. System updates project membership accordingly

This eliminates manual lookup and reduces administrator workload for organizations with large user bases.