@lap v0.3
# Machine-readable API spec. Each @endpoint block is one API call.
@api hashlookup CIRCL API
@version 1.3
@endpoints 11
@toc bulk(2), children(1), info(1), lookup(3), parents(1), session(2), stats(1)

@group bulk
@endpoint POST /bulk/md5
@desc Bulk search of MD5 hashes in a JSON array with the key 'hashes'.
@returns(200) Success
@errors {404: JSON format incorrect. An array of hashes in the key 'hashes' is expected.}

@endpoint POST /bulk/sha1
@desc Bulk search of SHA1 hashes in a JSON array with the 'hashes'.
@returns(200) Success
@errors {404: JSON format incorrect. An array of hashes in the key 'hashes' is expected.}

@endgroup

@group children
@endpoint GET /children/{sha1}/{count}/{cursor}
@desc Return children from a given SHA1.  A number of element to return and an offset must be given. If not set it will be the 100 first elements. A cursor must be given to paginate over. The starting cursor is 0.
@returns(200) Success
@errors {400: SHA1 value incorrect, expecting a SHA1 value in hex format, 404: The SHA1 value has no known child.}

@endgroup

@group info
@endpoint GET /info
@desc Info about the hashlookup database
@returns(200) Success

@endgroup

@group lookup
@endpoint GET /lookup/md5/{md5}
@desc Lookup MD5.
@returns(200) Success
@errors {400: MD5 value incorrect, expecting a MD5 value in hex format, 404: Non existing MD5}

@endpoint GET /lookup/sha1/{sha1}
@desc Lookup SHA-1.
@returns(200) Success
@errors {400: SHA1 value incorrect, expecting a SHA1 value in hex format, 404: Non existing SHA1}

@endpoint GET /lookup/sha256/{sha256}
@desc Lookup SHA-256.
@returns(200) Success
@errors {400: SHA-256 value incorrect, expecting a SHA-256 value in hex format, 404: Non existing SHA-256}

@endgroup

@group parents
@endpoint GET /parents/{sha1}/{count}/{cursor}
@desc Return parents from a given SHA1. A number of element to return and an offset must be given. If not set it will be the 100 first elements. A cursor must be given to paginate over. The starting cursor is 0.
@returns(200) Success
@errors {400: SHA1 value incorrect, expecting a SHA1 value in hex format, 404: The SHA1 value has no known parent.}

@endgroup

@group session
@endpoint GET /session/create/{name}
@desc Create a session key to keep search context. The session is attached to a name. After the session is created, the header `hashlookup_session` can be set to the session name.
@returns(200) Success
@errors {400: Expecting a name for the session, 500: Session feature is not enabled}

@endpoint GET /session/get/{name}
@desc Return set of matching and non-matching hashes from a session.
@returns(200) Success
@errors {400: Expecting a name for the session, 500: Session feature is not enabled}

@endgroup

@group stats
@endpoint GET /stats/top
@desc Return the top 100 of most queried values.
@returns(200) Success
@errors {400: Public statistics not enabled}

@endgroup

@end