APIs

Production

https://securitylabs.veracode.com

Endpoints

Authentication

Authentication: Header Format

-H "auth: key:secret"

Authentication: Header Example

-H "auth: 486a4f5d52daafac2aff4891156d9993400716e2:1e07a337896d4cbe60d1d143"

Credentials

Generate and manage your API credentials here. You need to include these in every request. See the example on the right.

Errors

Code	Message	Description
404	missing	credentials not found with your `key`
401	rotated	credentials found but `secret` has been changed
401	disabled	credentials valid but API is disabled
500	unknown	an unknown error was handled

Users

Get Users

Users: Get Users - Request

curl "/api/users?page=0" -H "auth: key:secret"

Users: Get Users - Response Format

{
  "nextPage" : String|Null,
  "users": [{
    "id": String,
    "email": String
    "isAdmin": Boolean,
    "isDisabled": Boolean,
    "joined": Boolean,
    "lastActive": Number,
    "roles": [
      String
    ]
  }]
}

Users: Get Users - Response Example

{
  "nextPage" : "/api/users?page=1", 
  "users": [{
    "id": "3bd68695e165af6ced227afc",
    "isAdmin": true,
    "isDisabled": false,
    "email": "developer@hunter2.com",
    "joined": true,
    "lastActive": 1557981546394, 
    "roles": [
      "Developers"
    ]
  }]
}

This endpoint retrieves all users.

Parameters

page (optional - page of users to get)

The parameter page is optional with a default value of 0. Results are limited to 10 items per page. Check nextPage in the response to see if there are additional items to fetch.

Errors

Code	Message	Description
500	unknown	an unknown error was handled

Make sure to use your key and secret.

Get Users Details

curl  "/api/users/details?campaignIds=5f5f18ff9dad493352660d2a,5f5f19099dad493352660d2b&roleIds=5f5f190f9dad493352660d2c,5f5f19159dad493352660d2d&startTime=1600067874107&endTime=1600067881636&sort=name&sortType=ASC&phrase=Chris&limit=10&page=0" -H "auth: key:secret"

Users: Get Users Details - Response Format

{
  "pages": {
    "current": Number,
    "previous": Number|null,
    "next": Number|null,
    "limit": Number,
    "total": Number,
    "currentUrl": String,
    "nextUrl": String|null,
    "previousUrl": String|null
  },
  "users": [{
    "id": String,
    "lastActive": Number|null,
    "labsCompleted": Number,
    "percentRequiredComplete": Number,
    "points": Number,
    "name": String,
    "roles": [{
      "id": String,
      "name": String
    }]
  }]
}

Users: Get Users Details - Response Example

{
  "pages": {
    "current": 1,
    "previous": 0,
    "next": 2,
    "limit": 10,
    "total": 25,
    "currentUrl": "/api/onboarding?campaignIds=5f5f18ff9dad493352660d2a,5f5f19099dad493352660d2b&roleIds=5f5f190f9dad493352660d2c,5f5f19159dad493352660d2d&startTime=1600067874107&endTime=1600067881636&sort=name&phrase=Chris&limit=10&page=0",
    "nextUrl": "/api/onboarding?campaignIds=6f5f18ff9dad493352660d2a,5f5f19099dad493352660d2b&roleIds=5f5f190f9dad493352660d2c,5f5f19159dad493352660d2d&startTime=1600067874107&endTime=1600067881636&sort=name&phrase=Chris&limit=10&page=1",
    "previousUrl": "/api/onboarding?campaignIds=6f5f18ff9dad493352660d2a,5f5f19099dad493352660d2b&roleIds=5f5f190f9dad493352660d2c,5f5f19159dad493352660d2d&startTime=1600067874107&endTime=1600067881636&sort=name&phrase=Chris&limit=10&page=0"
  },
  "users": [{
    "id": "5f5f18439dad493352660d28",
    "lastActive": 1600067617569,
    "name": "Chris Traeger",
    "labsCompleted": 1,
    "percentRequiredComplete": 50,
    "points": 10,
    "roles": [{
      "id": "5f5f184d9dad493352660d29",
      "name": "Security"
    }]
  }]
}

This endpoint retrieves users' details.

Parameters

campaignIds (optional - narrows content)
endTime (optional - narrows content)
limit (optional - number of users per page)
page (optional - page of users to get)
phrase (optional - narrows users)
roleIds (optional - narrows users)
startTime (optional - narrows content)
sort (optional - orders users)
sortType (optional - orders users)

The parameter campaignIds is optional. It should be a comma delimited list of campaign ids. If this parameter is absent the api will include all campaigns. Providing campaignIds narrows results by only including content associated with campaigns.

The parameter roleIds is optional. It should be a comma delimited list of role ids. If this parameter is absent and campaignIds is absent then all roles will be included. If this parameter is absent and campaignIds is present only roles from those campaigns will be used. If this parameter is present then only respective roles will be used. roleIds narrows results by only including associated users.

The parameters startTime and endTime are optional. They represent milliseconds since epoch. If included these parameters must appear together. These parameters narrow results by only including content assigned inside the time range.

The parameter limit is optional with a default of 10. If provided the value of this parameter must be greater than 0 and less or equal to 50.

The parameter sort is optional. The default sort value is name. All sort options incldue: name, role, milestone, and lastActive.

The parameter sortType is optional. The default sortType value is ASC. All sort type options incldue: ASC and DESC.

The parameter phrase is optional. If provided it only returns users that match the provided phrase by email or name.

Errors

Code	Message	Description
400	Invalid campaign id: String	The provided campaign id is invalid
400	Invalid role id: String	The provided role id is invalid
404	Campaign(s) not found by id(s): String	`campaignsIds` did not find campaign(s)
404	Role(s) not found by id(s): String	`roleIds` did not find role(s)
400	`startTime` is invalid	`startTime` is invalid
400	`startTime` is undefined	`endTime` was provided without a `startTime`
400	`endTime` is invalid	`endTime` is invalid
400	`endTime` is undefined	`startTime` was provided without an `endTime`
400	`sort` is invalid	`sort` value is not allowed
400	`sortType` is invalid	`sortType` value is not allowed
400	`limit` is invalid	`limit` is invalid
400	`phrase` must be less than 50 characters	`phrase` must be less than 50 characters
500	Unknown	An unknown error was handled

Make sure to use your key and secret.

Get User Progress

Users: Get User Progress - Request

curl "/api/users/:id/progress" -H "auth: key:secret"

Users: Get User Progress - Response Format

  {
    "pointsRequired": Number,
    "pointsPossible": Number,
    "lessons": [{
      "module": String,
      "lessonId": String,
      "lessonName": String,
      "lastVisited": String,
      "status": String,
      "minutes": Number,
      "points": Number,
      "startRating": Number,
      "endRating": Number|null,
    }]
  }

Users: Get User Progress - Response Example

{
  "pointsRequired": 10,
  "pointsPossible": 30,
  "lessons": [{
    "module": "OWASP #1: Injection",
    "lessonId": "5a5999d4ca50092ec5345ec4",
    "lessonName": "Own the database",
    "lastVisited": "3/4/2019",
    "status": "Started",
    "minutes": 1216.9,
    "points": 0,
    "startRating": 1,
    "endRating": 2
  }]
}

This endpoint retrieves progress for a user.

Parameters

page (optional - page of users to get)

The parameter page is optional with a default value of 0. Results are limited to 10 items per page. Check nextPage in the response to see if there are additional items to fetch.

Errors

Code	Message	Description
400	invalid user id	the format of the id is wrong
404	user not found	no user was found with that id
500	unknown	an unknown error was handled

Make sure to replace :id with the user id.

Make sure to use your key and secret.

Put User

This endpoint makes it possible to update the following user attributes: email, name, admin, disabled, and roles.

Users: Put User - Request Format

curl -0 -v -X PUT /api/users/:id \
-H "Content-Type: application/json" \
-H "auth: key:secret" \
-d @- <<'EOF'
{
  "email": String,
  "name": String,
  "admin": Boolean,
  "disabled": Boolean,
  "roleIds": Array
}
EOF

Users: Put User - Request Example

curl -0 -v -X PUT /api/users/:id \
-H "Content-Type: application/json" \
-H "auth: key:secret" \
-d @- <<'EOF'
{
  "email": "test@hunter2.com",
  "name": "test",
  "admin": false,
  "disabled": false,
  "roleIds": ["4acc432b734d1d55c318ef58"]
}
EOF

Users: Put User - Response Format

{
  "email": String,
  "name": String,
  "admin": Boolean,
  "disabled": Boolean, 
  "roleIds": Array
}

Users: Put User - Response Example

{
  "email": "test@hunter2.com",
  "name": "test",
  "admin": false, 
  "dsiabled": false,
  "roleIds": ["4acc432b734d1d55c318ef58"],
}

Errors

Code	Message	Description
400	User id is invalid	The user id is invalid
400	User not found	No user found with the user id
400	Email is invalid	The email is invalid
400	Name must be less than 25 characters	Name is too long
400	Invalid roleIds	Role ids is not an array
500	unknown	an unknown error was handled

Make sure to replace :id with the user id.

Make sure to use your key and secret.

Delete User

This endpoint deletes a user and all their resources.

Users: Delete User - Request

curl -X "DELETE" /api/users/:id

Users: Delete User - Response Format

{}

Users: Delete User - Response Example

{}

Errors

Code	Message	Description
400	User id is invalid	The user id is invalid
400	User not found	No user found with the user id
500	unknown	an unknown error was handled

Make sure to replace :id with the user id.

Make sure to use your key and secret.

Summaries

Get Onboarding

Summaries: Get Onboarding - Request

curl  "/api/onboarding?campaignIds=5f5f18ff9dad493352660d2a,5f5f19099dad493352660d2b&roleIds=5f5f190f9dad493352660d2c,5f5f19159dad493352660d2d&startTime=1600067874107&endTime=1600067881636&sort=name&sortType=ASC&phrase=Chris&limit=10&page=0" -H "auth: key:secret"

Summaries: Get Onboarding - Response Format

{
  "milestones": {
    "total": Number,
    "finished": Number,
    "notStarted": Number,
    "notSignedUp": Number,
    "started": Number
  },
  "pages": {
    "current": Number,
    "previous": Number|null,
    "next": Number|null,
    "limit": Number,
    "total": Number,
    "currentUrl": String,
    "nextUrl": String|null,
    "previousUrl": String|null
  },
  "users": [{
    "id": String,
    "lastActive": Number|null,
    "milestone": String,
    "name": String,
    "roles": [{
      "id": String,
      "name": String
    }]
  }]  
}

Summaries: Get Onboarding - Response Example

{
  "milestones": {
    "total": 1,
    "finished": 1,
    "notStarted": 0,
    "notSignedUp": 0,
    "started": 0
  },
  "pages": {
    "current": 1,
    "previous": 0,
    "next": 2,
    "limit": 10,
    "total": 25,
    "currentUrl": "/api/onboarding?campaignIds=5f5f18ff9dad493352660d2a,5f5f19099dad493352660d2b&roleIds=5f5f190f9dad493352660d2c,5f5f19159dad493352660d2d&startTime=1600067874107&endTime=1600067881636&sort=name&phrase=Chris&limit=10&page=0",
    "nextUrl": "/api/onboarding?campaignIds=6f5f18ff9dad493352660d2a,5f5f19099dad493352660d2b&roleIds=5f5f190f9dad493352660d2c,5f5f19159dad493352660d2d&startTime=1600067874107&endTime=1600067881636&sort=name&phrase=Chris&limit=10&page=1",
    "previousUrl": "/api/onboarding?campaignIds=6f5f18ff9dad493352660d2a,5f5f19099dad493352660d2b&roleIds=5f5f190f9dad493352660d2c,5f5f19159dad493352660d2d&startTime=1600067874107&endTime=1600067881636&sort=name&phrase=Chris&limit=10&page=0"
  },
  "users": [{
    "id": "5f5f18439dad493352660d28",
    "lastActive": 1600067617569,
    "name": "Chris Traeger",
    "milestone": "finished",
    "roles": [{
      "id": "5f5f184d9dad493352660d29",
      "name": "Security"
    }]
  }]
}

This endpoint provides onboarding analytics.

Parameters

campaignIds (optional - narrows content)
endTime (optional - narrows content)
limit (optional - number of users per page)
page (optional - page of users to get)
phrase (optional - narrows users)
roleIds (optional - narrows users)
startTime (optional - narrows content)
sort (optional - orders users)
sortType (optional - orders users)

The parameter limit is optional with a default of 10. If provided the value of this parameter must be greater than 0 and less or equal to 50.

The parameter sort is optional. The default sort value is name. All sort options incldue: name, role, milestone, and lastActive.

The parameter sortType is optional. The default sortType value is ASC. All sort type options incldue: ASC and DESC.

The parameter phrase is optional. If provided it only returns users that match the provided phrase by email or name.

Milestones

The milestones below represent number of users:

total (all milestones combined; all users)
finished (finished a lab)
notStarted (not started a lab)
notSignedUp (not signed up)
started (started a lab)

Errors

Code	Message	Description
400	Invalid campaign id: String	The provided campaign id is invalid
400	Invalid role id: String	The provided role id is invalid
404	Campaign(s) not found by id(s): String	`campaignsIds` did not find campaign(s)
404	Role(s) not found by id(s): String	`roleIds` did not find role(s)
400	`startTime` is invalid	`startTime` is invalid
400	`startTime` is undefined	`endTime` was provided without a `startTime`
400	`endTime` is invalid	`endTime` is invalid
400	`endTime` is undefined	`startTime` was provided without an `endTime`
400	`sort` is invalid	`sort` value is not allowed
400	`sortType` is invalid	`sortType` value is not allowed
400	`limit` is invalid	`limit` is invalid
400	`phrase` must be less than 50 characters	`phrase` must be less than 50 characters
500	Unknown	An unknown error was handled

Make sure to use your key and secret.

Get Campaigns Progress

Summaries: Get Campaigns Progress - Request

curl  "/api/campaigns/progress?campaignIds=5f5f18ff9dad493352660d2a,5f5f19099dad493352660d2b&roleIds=5f5f190f9dad493352660d2c,5f5f19159dad493352660d2d&sort=name&sortType=ASC&phrase=Chris&limit=10&page=0" -H "auth: key:secret"

Summaries: Get Campaigns Progress - Response Format

{
  "milestones": {
    "total": Number,
    "finished": Number,
    "notStarted": Number,
    "started": Number
  },
  "assignments": [{
    "title": String,
    "labs": [{
      "title": String,
      "milestones" : {
        "total": Number,
        "finished": Number,
        "notStarted": Number,
        "started": Number
      }
    }]
  }],
  "pages": {
    "current": Number,
    "previous": Number|null,
    "next": Number|null,
    "limit": Number,
    "total": Number,
    "currentUrl": String,
    "nextUrl": String|null,
    "previousUrl": String|null
  },
  "users": [{
    "id": String,
    "lastActive": Number|null,
    "milestone": String,
    "name": String,
    "roles": [{
      "id": String,
      "name": String
    }]
  }]  
}

Summaries: Get Campaigns Progress - Response Example

{
  "milestones": {
    "total": 1,
    "finished": 1,
    "notStarted": 0,
    "started": 0
  },
  "assignments": [{
    "title": "OWASP",
    "labs": [{ 
      "title": "SQLI",
      "milestones" : {
        "total": 1,
        "finished": 1,
        "notStarted": 0,
        "started": 0 
      }
    }]
  }],
  "pages": {
    "current": 1,
    "previous": 0,
    "next": 2,
    "limit": 10,
    "total": 25,
    "currentUrl": "/api/onboarding?campaignIds=5f5f18ff9dad493352660d2a,5f5f19099dad493352660d2b&roleIds=5f5f190f9dad493352660d2c,5f5f19159dad493352660d2d&startTime=1600067874107&endTime=1600067881636&sort=name&phrase=Chris&limit=10&page=0",
    "nextUrl": "/api/onboarding?campaignIds=6f5f18ff9dad493352660d2a,5f5f19099dad493352660d2b&roleIds=5f5f190f9dad493352660d2c,5f5f19159dad493352660d2d&startTime=1600067874107&endTime=1600067881636&sort=name&phrase=Chris&limit=10&page=1",
    "previousUrl": "/api/onboarding?campaignIds=6f5f18ff9dad493352660d2a,5f5f19099dad493352660d2b&roleIds=5f5f190f9dad493352660d2c,5f5f19159dad493352660d2d&startTime=1600067874107&endTime=1600067881636&sort=name&phrase=Chris&limit=10&page=0"
  },
  "users": [{
    "id": "5f5f18439dad493352660d28",
    "lastActive": 1600067617569,
    "name": "Chris Traeger",
    "milestone": "finished",
    "roles": [{
      "id": "5f5f184d9dad493352660d29",
      "name": "Security"
    }]
  }]
}

This endpoint provides progress at the campaign or assignment level.

Parameters

assignmentIds (optional - narrows content)
campaignIds (optional - narrows content)
includeOptionalLabs (optional - widens content)
limit (optional - number of users per page)
page (optional - page of users to get)
phrase (optional - narrows users)
roleIds (optional - narrows users)
sort (optional - orders users)
sortType (optional - orders users)

The parameter assignmentIds is optional. It should be a comma delimited list of assignment ids. If this parameter is absent the api will assume assignments from campaigns. Providing assignmentIds narrows results by only including content associated with assignments.

The parameters assignmentIds and campaignIds are mutually exclusive. If assignmentIds is present then campaigns will come from assignments. If campaignIds is present then assignments will come from campaigns.

The parameter includeOptionalLabs includes all labs marked required and optional.

The parameter limit is optional with a default of 10. If provided the value of this parameter must be greater than 0 and less or equal to 50.

The parameter sort is optional. The default sort value is name. All sort options incldue: name, role, milestone, and lastActive.

The parameter sortType is optional. The default sortType value is ASC. All sort type options incldue: ASC and DESC.

The parameter phrase is optional. If provided it only returns users that match the provided phrase by email or name.

Milestones

The milestones below represent number of users:

total (all milestones combined; all users)
finished (finished all lab)
notStarted (not started a lab)
started (started a lab)

Errors

Code	Message	Description
400	`assignmentIds` and `campaignIds` are mutually exclusive	Either `assignmentIds` or campaignIds can be present, not both
400	Invalid assignment id: String	The provided assignment id is invalid
400	Invalid campaign id: String	The provided campaign id is invalid
400	Invalid role id: String	The provided role id is invalid
404	Campaign(s) not found by id(s): String	`campaignsIds` did not find campaign(s)
404	Role(s) not found by id(s): String	`roleIds` did not find role(s)
400	`sort` is invalid	`sort` value is not allowed
400	`sortType` is invalid	`sortType` value is not allowed
400	`limit` is invalid	`limit` is invalid
400	`phrase` must be less than 50 characters	`phrase` must be less than 50 characters
500	Unknown	An unknown error was handled

Make sure to use your key and secret.

Get Engagement Time

Summaries: Get Engagement Time - Request

curl "/api/engagement/time?campaignIds=5f5f18ff9dad493352660d2a,5f5f19099dad493352660d2b&roleIds=5f5f190f9dad493352660d2c,5f5f19159dad493352660d2d" -H "auth: key:secret"

Summaries: Get Engagement Time - Response Format

{
  "duration" : Number
}

Summaries: Get Engagement Time - Response Example

{
  "duration" : 1800000 
}

This endpoint returns the median time users spend on labs.

Parameters

assignmentIds (optional - narrows content)
campaignIds (optional - narrows content)
roleIds (optional - narrows users)

Duration

Duration is the median time users spend on labs in milliseconds.

Errors

Code	Message	Description
400	`assignmentIds` and `campaignIds` are mutually exclusive	Either `assignmentIds` or campaignIds can be present, not both
400	Invalid assignment id: String	The provided assignment id is invalid
400	Invalid campaign id: String	The provided campaign id is invalid
400	Invalid role id: String	The provided role id is invalid
404	Assignments(s) not found by id(s): String	`assignmentIds` did not find assignments(s)
404	Campaign(s) not found by id(s): String	`campaignsIds` did not find campaign(s)
404	Role(s) not found by id(s): String	`roleIds` did not find role(s)
500	Unknown	An unknown error was handled

Make sure to use your key and secret.

Get Progress

Summaries: Get Progress - Request

curl "/api/progress?page=0" -H "auth: key:secret"

Summaries: Get Progress - Response Format

{
  "nextPage": String|Null,
  "users": [{
    "id": String, 
    "email": String, 
    "name": String,
    "labsCompleted": Number,
    "lastActive": Number,
    "totalPoints": Number,
    "labsStarted": Number,
    "accountDisabled": Boolean,
    "requiredCompletionPercent": Number,
    "pointsRequired" : Number,
    "pointsPossible" : Number,
    "lessons": [{
      "lessonId": String,
      "lessonName": String,
      "module": String,
      "startTime": Number,
      "endTime": String|null,
      "startRating": Number,
      "endRating": Number|null,
      "lastStepReached": Number,
      "status": String,
      "points": Number
    }],
    "roles": [
      String
    ]
  }]
}

Summaries: Get Progress - Response Example

{
  "nextPage": "/api/progress?page=1",
  "users": [{
    "id": "3bd68695e165af6ced227afc",
    "email": "test@hunter2.com",
    "name": "Test User",
    "labsCompleted": 1,
    "lastActive": "3/6/2019",
    "totalPoints": 10,
    "labsStarted": 2,
    "disabled": false,
    "requiredCompletionPercent": 14,
    "pointsRequired" : 10,
    "pointsPossible" : 30,
    "lessons": [{
      "lessonId": "5a5999d4ca50092ec5345ec4",
      "lessonName": "Own the database",
      "module": "OWASP #1: Injection",
      "startTime": 1551673334046,
      "endTime": 1551673334047,
      "startRating": 1,
      "endRating": 2,
      "lastStepReached": 1,
      "status": "Finished"
    }]
    "roles": [
      "Developers"
    ]
  }]
}

This endpoint retrieves progress for an entire team.

Parameters

page (optional - page of users to get)

The parameter page is optional with a default value of 0. Results are limited to 10 items per page. Check nextPage in the response to see if there are additional items to fetch.

Errors

Code	Message	Description
500	unknown	an unknown error was handled

Make sure to use your key and secret.

Lessons

Get Lessons

Lessons: Get Lessons - Request

curl "/api/lessons?page=0" -H "auth: key:secret"

Lessons: Get Lessons - Response Format

{
  "nextPage": String|Null,
  "lessons": [{
    "id": String, 
    "title": String, 
    "module": String, 
    "points": Number, 
    "roles": [
      String
    ]
  }]
}

Lessons: Get Lessons - Response Example

{
  "nextPage": "/api/lessons?page=1",
  "lessons": [{
    "id": "5a5999d4ca50092ec5345ec4",
    "title": "Own the database",
    "module": "OWASP #1: Injection",
    "points": 20, 
    "roles": [
      "Developers"
    ]
  }]
}

This endpoint retrieves a team's lessons.

Parameters

page (optional - page of users to get)

The parameter page is optional with a default value of 0. Results are limited to 10 items per page. Check nextPage in the response to see if there are additional items to fetch.

Errors

Code	Message	Description
500	unknown	an unknown error was handled

Make sure to use your key and secret.

Get Lesson Progress

Lessons: Get Lesson Progress - Request

curl "/api/lessons/:id/progress?page=0" -H "auth: key:secret"

Lessons: Get Lesson Progress - Response Format

{  
   "nextPage": String|Null, 
   "id": String, 
   "title": String, 
   "module": String, 
   "points": Number,
   "roles": [
      String
    ],
   "users": [{
     "id": String,
     "startTime": Number|null,
     "endTime": String|null,
     "startRating": Number|null,
     "endRating": Number|null,
     "lastStepReached": Number|null,
     "status": String
    }]
}

Lessons: Get Lesson Progress - Response Example

{
  "nextPage": "/api/lessons/5a5999d4ca50092ec5345ec4/progress?page=1",
  "id": "5a5999d4ca50092ec5345ec4",
  "title": "Own the database",
  "module": "OWASP #1: Injection",
  "points": 30,
  "roles": [
    "Developers"
  ],
  "users": [{
    "id": "3bd68695e165af6ced227afc",
    "startTime": 1551673334046,
    "endTime": 1551673334047,
    "startRating": 1,
    "endRating": 4,
    "lastStepReached": 1,
    "status": "Started"
  }]
}

This endpoint retrieves user progress for a lesson.

Parameters

page (optional - page of users to get)

The parameter page is optional with a default value of 0. Results are limited to 10 items per page. Check nextPage in the response to see if there are additional items to fetch.

Errors

Code	Message	Description
400	invalid lesson id	the format of the id is wrong
404	lesson not found	no lesson was found with that id
500	unknown	an unknown error was handled

Make sure to replace id with your lesson id.

Make sure to use your key and secret.

Get Lesson By Topic

Lessons: Get Lesson By Topic - Request

curl "/api/lessons/search?phrase=XSS" -H "auth: key:secret"

Lessons: Get Lesson By Topic - Response Format

{ 
  "pages": {
    "current": Number,
    "previous": Number,
    "next": Number|null,
    "limit": Number,
    "currentUrl": String, 
    "nextUrl": String|null, 
    "previousUrl": String|null,
    "total": Number
  },
  "lessons": [
    { 
      "challenge": Boolean,
      "description": String,
      "stack": String,
      "tags": Array,
      "title": String,
      "topic": String,
      "url": String
    }
  ]
}

Lessons: Get Lesson By Topic - Response Example

{
  "pages": {
    "current": 1,
    "previous": 0,
    "next": null,
    "limit": 10,
    "currentUrl": '/api/lessons/search?limit=10&page=1',
    "nextUrl": null,
    "previousUrl": null ,
    "total": 1
  },
  "lessons": [
    {
      "challenge": false,
      "description": 'Decrypt cookies and hijack another user account.',
      "stack": 'node',
      "tags": ['Node.js'],
      "title": 'Bad Cookie',
      "topic": 'secure cookies for user sessions',
      "url": '/lesson/bad-cookie'
    }
  ]
}

This endpoint retrieves lessons given a phrase which will be used to search tags. If no phrase is given all lessons will be returned. Tags are topics and technologies covered by the lab, such as "OWASP #8", "CWE-601", or "Python".

Parameters

limit (optional - number of lessons per page)
page (optional - page of lessons to get)
phrase (optional - string to search lessons by tags)

The parameter page is optional with a default value of 0. Results are limited to 10 items per page. Check nextPage in the response to see if there are additional items to fetch.

Errors

Code	Message	Description
400	invalid phrase	must be a string between 0 and 300 [characters in length]
500	unknown	an unknown error was handled

Make sure to use your key and secret.

Roles

Get Roles

This endpoint retrieves a team's roles.

Roles: Get Roles - Request

curl "/api/roles" -H "auth: key:secret"

Roles: Get Roles - Response Format

[{
  "id": String,
  "name": String,
  "default": Boolean,
  "public": Boolean,
  "users": [
    String
  ],
  "invitedUsers": [
    String
  ]
}]

Roles: Get Roles - Response Example

[{
  "id": "4bd68695e165af6ced227afz",
  "name": "Developers",
  "default": true,
  "public": false,
  "users": [
    "3bd68695e165af6ced227afc"
  ],
  "invitedUsers": [
    "5ce34b1b0e5f930030014122"
  ]
}]

Errors

Code	Message	Description
500	unknown	an unknown error was handled

Make sure to use your key and secret.

Get Role Progress

Roles: Get Role Progress - Request

curl "/api/roles/:id/progress?page=0" -H "auth: key:secret"

Roles: Get Role Progress - Response Format

[{
  "nextPage": String|Null, 
  "id": String,
  "name": String,
  "users": [{
    "id": String,
    "email": String,
    "name": String,
    "percentComplete": Number,
    "percentRequiredComplete": Number
  }]
}]

Roles: Get Role Progress - Response Example

[{
  "nextPage": "/api/roles/4bd68695e165af6ced227afz/progress?page=1",
  "id": "4bd68695e165af6ced227afz",
  "name": "Developers",
  "users": [{
    "id": "3bd68695e165af6ced227afc",
    "email": "test@hunter2.com",
    "name": "Test User",
    "percentComplete": 50,
    "percentRequiredComplete": 100
  }]
}]

This endpoint retrieves progress for a team role.

Parameters

page (optional - page of users to get)

The parameter page is optional with a default value of 0. Results are limited to 10 items per page. Check nextPage in the response to see if there are additional items to fetch.

Errors

Code	Message	Description
500	unknown	an unknown error was handled
404	Role not found	could not find role with given id
403	Role does not belong to team	role does not belong to team

Make sure to use your key and secret.

Invites

Post Invites

This endpoint can be used to invite users to a team. Invited users will be automatically assigned to the team associated with the API credentials. Upon invite creation, any default role(s) will be assigned to the invited user as well.

Invites: Post Invites - Request Format

curl -0 -v POST /api/invites \
-H "Content-Type: application/json" \
-H "auth: key:secret" \
-d @- <<'EOF'
  {
    "email": String, 
    "senderId": String,
    "roleIds": Array, 
    "admin": Boolean,
    "sendEmail": Boolean 
  }
EOF

Invites: Post Invites - Request Example

curl -0 -v POST /api/invites \
-H "Content-Type: application/json" \
-H "auth: key:secret" \
-d @- <<'EOF'
{ 
  "email": "test@hunter2.com",
  "senderId": "cb4f412c59ef801d0e6de1c6",
  "roleIds": ["4acc432b734d1d55c318ef58"],
  "admin": false,
  "sendEmail": true
}
EOF

Invites: Post Invites - Response Format

{
  "email": String, 
  "admin": Boolean, 
  "roleIds": Array,
  "senderId": String
}

Invites: Post Invites - Response Example

{ 
  "email": "test@hunter2.com",
  "senderId": "cb4f412c59ef801d0e6de1c6",
  "roleIds": ["4acc432b734d1d55c318ef58"],
  "admin": false,
}

Errors

Code	Message	Description
400	Email is invalid	The posted invite email is invalid
400	Role ids are invalid	The posted role ids is not an array
400	Sender id is invalid	The id of the user to send the email is invalid
400	Sender not found	The user to send the email could not be found
400	Invite already exists	An invite for that email and team exists
500	unknown	an unknown error was handled

Make sure to use your key and secret.

APIs

Production

Endpoints

Users

Summaries

Lessons

Roles

Invites

Authentication

Credentials

Errors

Users

Get Users

Parameters

Errors

Get Users Details

Parameters

Pages

Errors

Get User Progress

Parameters

Errors

Put User

Errors

Delete User

Errors

Summaries

Get Onboarding

Parameters

Milestones

Pages

Errors

Get Campaigns Progress

Parameters

Milestones

Pages

Errors

Get Engagement Time

Parameters

Duration

Errors

Get Progress

Parameters

Errors

Lessons

Get Lessons

Parameters

Errors

Get Lesson Progress

Parameters

Errors

Get Lesson By Topic

Parameters

Errors

Roles

Get Roles

Errors

Get Role Progress

Parameters

Errors

Invites

Post Invites

Errors